switchroom 0.7.15 → 0.10.0

package/examples/minimal.yaml

@@ -0,0 +1,63 @@
+# switchroom.yaml — Minimal single-agent setup.
+# One bot, one agent, DM-only (no forum/topic routing).
+#
+# `vault:telegram-bot-token` is the canonical way to reference the bot
+# token — `switchroom setup` stores your BotFather token in the vault
+# under that key and the runtime resolves it via the vault broker.
+# (For bootstrap before the vault exists, the wizard also accepts
+# TELEGRAM_BOT_TOKEN as an env-var fallback.)
+#
+# `forum_chat_id: "0"` is the DM-only sentinel used by v0.7+ — kept in
+# the schema for backwards compat with legacy forum-mode installs.
+
+switchroom:
+  version: 1
+
+telegram:
+  bot_token: "vault:telegram-bot-token"
+  forum_chat_id: "0"
+
+memory:
+  backend: hindsight
+  shared_collection: shared
+
+defaults:
+  model: claude-sonnet-4-6
+  tools:
+    allow: [all]
+  subagents:
+    worker:
+      description: "Handles implementation tasks: writing, editing, building, testing. Use for any task that takes more than a few seconds."
+      model: sonnet
+      background: true
+      isolation: worktree
+      maxTurns: 50
+      color: blue
+      prompt: |
+        You are a worker sub-agent. Implement the task described in your
+        prompt precisely and completely. Commit your work when done.
+        If requirements are ambiguous, state your assumptions rather
+        than guessing. Return a concise summary of what you did.
+    researcher:
+      description: "Explores codebases, reads documentation, searches for information. Use for any research or investigation task."
+      model: haiku
+      background: true
+      color: green
+      prompt: |
+        You are a research sub-agent. Investigate the topic described
+        in your prompt thoroughly. Return structured findings — not
+        raw file contents. Keep your report under 500 words unless
+        the parent explicitly asks for more detail.
+    reviewer:
+      description: "Reviews code, plans, documents for quality, correctness, and completeness. Use after a worker finishes or before shipping."
+      model: sonnet
+      color: purple
+      prompt: |
+        You are a review sub-agent. Examine the work described in
+        your prompt for correctness, completeness, security, and
+        quality. Report findings as a punch list: what's good, what
+        needs fixing, what's missing. Be rigorous but concise.
+
+agents:
+  assistant:
+    topic_name: "General"

package/examples/personal-google-workspace-mcp/.env.example

@@ -0,0 +1,34 @@
+# Personal Google Workspace MCP — environment configuration.
+#
+# Copy to `.env` and fill in:
+#   GOOGLE_OAUTH_CLIENT_ID    — from your Google Cloud Console OAuth client (Desktop app type)
+#   FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY — generate via: openssl rand -hex 32
+#
+# OAuth 2.1 PKCE flow — no client_secret needed (Desktop clients are
+# public clients per OAuth 2.0 spec; PKCE replaces the secret's role).
+
+# Required by upstream MCP for OAuth 2.1 mode.
+MCP_ENABLE_OAUTH21=true
+
+# Your OAuth client ID from Google Cloud Console.
+# Create: APIs & Services → Credentials → Create OAuth client ID → Desktop app.
+# Format: "12345678-abc...xyz.apps.googleusercontent.com"
+GOOGLE_OAUTH_CLIENT_ID=REPLACE_WITH_YOUR_CLIENT_ID
+
+# Port the MCP server listens on (must match compose.yaml's port mapping
+# AND the URL in your .mcp.json). 8217 is arbitrary; pick anything free.
+WORKSPACE_MCP_PORT=8217
+
+# OAuth callback URL — must match WORKSPACE_MCP_PORT exactly.
+# Loopback `localhost` is implicitly allowed for Desktop OAuth clients,
+# no GCP-side redirect URI registration needed.
+GOOGLE_OAUTH_REDIRECT_URI=http://localhost:8217/oauth2callback
+
+# Required for the loopback OAuth flow over plain HTTP. Safe in this
+# context — the OAuth handshake never leaves localhost.
+OAUTHLIB_INSECURE_TRANSPORT=1
+
+# JWT signing key for the MCP's session tokens. Generate ONCE per
+# install:  openssl rand -hex 32
+# DO NOT commit the real value to source control.
+FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY=REPLACE_WITH_HEX_FROM_OPENSSL_RAND

package/examples/personal-google-workspace-mcp/README.md

@@ -0,0 +1,194 @@
+# Personal Google Workspace MCP
+
+This example sets up [taylorwilsdon/google_workspace_mcp][upstream] as a
+docker-compose service exposing Google Drive + Docs + Sheets + Calendar
+tools to **your own Claude Code session on the host** (not to switchroom
+agents).
+
+It is intentionally **separate from the agent-side feature.** Agents get
+Workspace access via `switchroom auth google connect <agent>` (RFC G
+§4.5, available after Phase 3 lands). This example is for the
+operator's pair-design loop with their own host-side `claude`.
+
+> **Why two paths?** Agents run inside switchroom containers with
+> approval-kernel-mediated tool access; the per-agent OAuth posture is
+> load-bearing for the approval semantics (RFC D §2 + RFC G §4.4).
+> Your own host-side Claude Code is a single-identity surface — none of
+> that machinery applies. A shared HTTP MCP server is the right shape
+> for the operator case and the wrong shape for the fleet.
+
+[upstream]: https://github.com/taylorwilsdon/google_workspace_mcp
+
+## What you get
+
+- A long-running docker container (`google-workspace-mcp`) listening on
+  loopback port 8217.
+- 16 Workspace tools available to any Claude Code session that points
+  its `.mcp.json` at `http://127.0.0.1:8217/mcp`.
+- OAuth 2.1 PKCE flow — no client_secret to manage.
+- Refresh tokens persist in `./credentials/` so you re-auth only on
+  Google password change or 7-day Testing-mode expiry (see §5).
+
+## What you don't get
+
+- Tools in unrelated Claude Code sessions. The `.mcp.json` is
+  project-scoped — Drive surface only appears when you `cd` to a
+  directory that has it.
+- Any effect on switchroom agents.
+- HTTPS or LAN reachability. Loopback only by design.
+
+## 1. GCP Console setup (~5 minutes, you do this)
+
+1. Go to <https://console.cloud.google.com> and create (or pick) a
+   project — name it `claude-workspace-mcp`.
+2. **APIs & Services → Library** — enable each of these (one at a time;
+   wait for "API enabled" before moving on):
+   - Google Drive API
+   - Google Docs API
+   - Google Sheets API
+   - Google Calendar API
+3. **APIs & Services → OAuth consent screen** → User Type **External**.
+   - Fill App name (`claude-workspace-mcp`), your email, dev contact email.
+   - Save and continue past the Scopes page (the server requests scopes
+     at runtime — don't add any here).
+   - **Add yourself as a Test User** under "Audience" (your gmail
+     address).
+   - Decide whether to **Publish app** — see §5 for the trade-off.
+4. **APIs & Services → Credentials → Create Credentials → OAuth client
+   ID** → Application type **Desktop app** → name it `claude-code-local`.
+5. Copy the Client ID from the modal (looks like
+   `12345-abc...xyz.apps.googleusercontent.com`). You can ignore the
+   client secret — PKCE doesn't use it.
+
+## 2. Set up this directory
+
+```sh
+cd examples/personal-google-workspace-mcp/
+cp .env.example .env
+
+# Edit .env:
+#   GOOGLE_OAUTH_CLIENT_ID   ← paste from step 5 above
+#   FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY ← generate via:
+
+# (GNU sed — Linux)
+sed -i "s|REPLACE_WITH_HEX_FROM_OPENSSL_RAND|$(openssl rand -hex 32)|" .env
+
+# (BSD sed — macOS — use this instead)
+# sed -i '' "s|REPLACE_WITH_HEX_FROM_OPENSSL_RAND|$(openssl rand -hex 32)|" .env
+
+chmod 600 .env
+```
+
+## 3. Bring it up
+
+```sh
+docker compose up -d
+docker compose ps          # should show "healthy" within ~30s
+docker compose logs -f     # ctrl-c when you see "Uvicorn running on http://0.0.0.0:8217"
+```
+
+## 4. Wire it into Claude Code
+
+Choose where the MCP server should be reachable:
+
+**Project-scoped (recommended)** — the Workspace tools only appear when
+you start Claude Code in this specific project directory:
+
+```sh
+cat > /path/to/your/project/.mcp.json <<'JSON'
+{
+  "mcpServers": {
+    "google-workspace": {
+      "type": "http",
+      "url": "http://127.0.0.1:8217/mcp"
+    }
+  }
+}
+JSON
+```
+
+Restart Claude Code in that directory. On first start it'll prompt to
+approve the new MCP server — say yes.
+
+**User-scoped** (every Claude Code session sees Workspace tools): use
+`claude mcp add` instead per upstream README — but think hard before you
+do this, because you're then carrying Workspace authorization into every
+unrelated codebase.
+
+## 5. OAuth consent — Testing vs Production trade-off
+
+When you set up the consent screen in §1.3, you chose between leaving
+the app in **Testing** or clicking **Publish app**.
+
+- **Testing** (default): refresh tokens expire **every 7 days** for
+  Google's "unverified app + sensitive scopes" policy. You re-auth
+  weekly via the inline OAuth prompt.
+- **Production**: no 7-day expiry. The "Publish app" button prompts
+  scary copy ("your app will be available to any user with a Google
+  Account") but for a personal Desktop OAuth client with you as the
+  only user, this is effectively a no-op — there's nothing to find or
+  use without your specific Client ID.
+
+Pick whichever your nerve allows.
+
+## 6. Tier choice
+
+`compose.yaml` defaults to `--tool-tier core` (~16 tools). Change to:
+
+- `extended` (~40 tools) — adds Slides, Forms, Tasks, Chat. Re-consent
+  needed (broader OAuth scopes). Procedure:
+  1. Edit `compose.yaml` to bump `--tool-tier core` → `--tool-tier extended`.
+  2. **Delete the existing token** so the upgraded scopes get requested
+     on the next OAuth flow: `rm -rf ./credentials/`.
+  3. `docker compose up -d --force-recreate`.
+  4. Trigger a tool call from Claude Code — the OAuth URL will appear
+     inline; tap to consent at the new scopes.
+- `complete` (~60+ tools) — adds Gmail. **Not recommended yet** — Gmail's
+  per-thread approval shape is unsuitable for the broad OAuth scopes
+  this tier requests. Wait for a dedicated Gmail spec.
+
+## 7. Maintenance
+
+- **Logs**: `docker compose logs -f workspace-mcp`
+- **Restart**: `docker compose restart workspace-mcp`
+- **Re-auth** (Google password change or weekly Testing expiry): the
+  next failed tool call surfaces a fresh OAuth URL inline; tap to
+  consent, done.
+- **Upgrade**: bump the `workspace-mcp==X.Y.Z` pin in `compose.yaml`,
+  then `docker compose up -d --force-recreate`.
+- **Tear down**: `docker compose down` (keeps credentials);
+  `docker compose down -v` (deletes credentials, forces fresh OAuth).
+- **Inspect tokens**: `ls -la ./credentials/` — one JSON file per
+  authenticated Google account.
+
+## 8. Troubleshooting
+
+- **Container "unhealthy" forever**: check `docker compose logs` for
+  Python tracebacks. Most common cause: `GOOGLE_OAUTH_CLIENT_ID` or
+  `FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY` still has the
+  `REPLACE_WITH_*` placeholder.
+- **Port 8217 collision**: bump the port in `.env`
+  (`WORKSPACE_MCP_PORT` + `GOOGLE_OAUTH_REDIRECT_URI`), in
+  `compose.yaml` (the `ports:` mapping AND the healthcheck script),
+  and in your `.mcp.json` URL.
+- **OAuth flow fails with `redirect_uri_mismatch`**: make sure
+  `GOOGLE_OAUTH_REDIRECT_URI` in `.env` exactly matches
+  `WORKSPACE_MCP_PORT`. Loopback URIs don't need GCP-side registration
+  for Desktop clients, but they do need to match what the server
+  presents.
+- **Claude Code doesn't show the new MCP server after `cd` to project**:
+  exit and re-launch Claude Code (`/exit`, then `claude -c` to keep
+  the conversation). `.mcp.json` is loaded at startup, not hot-reloaded.
+
+## 9. Security notes
+
+- `.env` is mode 600 — don't commit, don't share, don't snapshot.
+- `./credentials/` directory holds refresh tokens — same restrictions.
+  Add to disk-encryption scope if your host has any.
+- The Workspace MCP sends data to Google APIs only, on your behalf,
+  using your OAuth client. No telemetry, no third-party endpoints
+  (verified per upstream's `pyproject.toml` dependency tree).
+- The OAuth client_secret in your `gcp-oauth.keys.json` (if Google
+  Cloud Console gave you one) is **not used** in PKCE flow. Treat it
+  as cosmetic; you can ignore it. If it's worried you, regenerate it
+  in GCP Console — won't break anything.

package/examples/personal-google-workspace-mcp/compose.yaml

@@ -0,0 +1,66 @@
+# Personal Google Workspace MCP — operator-host Claude Code surface.
+#
+# This is the docker-compose pattern for an operator who wants their own
+# Claude Code on the host to have Drive + Docs + Sheets + Calendar tools.
+# It does NOT affect switchroom agents — they get Workspace via
+# `switchroom auth google connect <agent>` (RFC G §4.5, post-Phase-3).
+#
+# Setup walkthrough: see README.md.
+#
+# Compose project name (`name:`) is deliberately distinct from the
+# `switchroom` project so `switchroom apply` / `switchroom update` /
+# `docker compose -p switchroom down -v` won't touch this container.
+# Same isolation pattern as the hostd compose project.
+
+name: google-workspace-mcp
+
+services:
+  workspace-mcp:
+    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+    container_name: google-workspace-mcp
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      WORKSPACE_MCP_CREDENTIALS_DIR: /credentials
+    ports:
+      # Loopback only — never expose Workspace MCP to the LAN.
+      # Bump the host-side port if 8217 collides with something else
+      # (also update WORKSPACE_MCP_PORT + GOOGLE_OAUTH_REDIRECT_URI in .env
+      # and the URL in your .mcp.json).
+      - "127.0.0.1:8217:8217"
+    volumes:
+      # Refresh tokens persist here (chmod 700-equivalent inside the
+      # container). Survives container recreate; lost on `docker compose
+      # down -v`.
+      - ./credentials:/credentials
+    command:
+      - uvx
+      # Pinned: bumping is a deliberate operator decision, not a silent
+      # surprise. Bump in lockstep with retesting the OAuth flow.
+      - --from
+      - workspace-mcp==1.20.4
+      - workspace-mcp
+      # streamable-http (not stdio) is required for OAuth 2.1 PKCE per
+      # upstream README.
+      - --transport
+      - streamable-http
+      # Tier knob — see README §4 for tier choice. `core` = ~16 tools
+      # (Drive + Docs + Sheets + Calendar, the validated default).
+      - --tool-tier
+      - core
+      # Restrict to only the four core services; omits Gmail (which is
+      # in `complete` tier and warrants its own approval shape).
+      - --tools
+      - drive
+      - docs
+      - sheets
+      - calendar
+    healthcheck:
+      # TCP-connect probe — the server returns 401 on `/mcp` until OAuth
+      # completes, which would fail an HTTP healthcheck. TCP-connect just
+      # verifies the listener is bound.
+      test: ["CMD-SHELL", "python -c \"import socket; s=socket.socket(); s.settimeout(2); s.connect(('127.0.0.1',8217)); s.close()\""]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s

package/examples/switchroom.yaml

@@ -0,0 +1,220 @@
+# switchroom.yaml — Full example configuration
+#
+# Switchroom uses a three-layer cascade for agent config:
+#   1. defaults:  → global baseline for every agent
+#   2. profiles:  → named presets agents opt into via `extends:`
+#   3. agents:    → per-agent overrides (only express differences)
+#
+# Each agent gets its own Telegram topic in a forum group.
+# Create bots via @BotFather: /newbot for each agent.
+
+switchroom:
+  version: 1
+  agents_dir: ~/.switchroom/agents
+  skills_dir: ~/.switchroom/skills           # shared skill pool (symlinked per agent)
+
+telegram:
+  bot_token: "vault:telegram-bot-token"
+  # DM-only sentinel; v0.7+ defaults to per-agent DM-pair topology.
+  # Legacy forum-mode installs keep a real chat id here.
+  forum_chat_id: "0"
+
+memory:
+  backend: hindsight
+  shared_collection: shared
+  config:
+    provider: ollama
+    model: nomic-embed-text
+
+vault:
+  # v0.7.12+ canonical path is the parent-dir layout. v0.7.x installs
+  # auto-migrate from the legacy ~/.switchroom/vault.enc on `switchroom
+  # apply`; the legacy path becomes a symlink that's removed in v0.7.14.
+  # See docs/vault.md for the migration story.
+  path: ~/.switchroom/vault/vault.enc
+
+# --- Global defaults (implicit bottom-of-cascade profile) ---
+# Every agent inherits this. Per-agent fields win on conflict.
+# tools/skills/schedule are unioned; scalars are overridden.
+defaults:
+  model: claude-sonnet-4-6
+  # The switchroom-telegram fork is the default. Uncomment to fall back to
+  # the upstream marketplace plugin: channels.telegram.plugin: official
+  channels:
+    telegram:
+      format: html
+  tools:
+    allow: [all]
+  env:
+    SWITCHROOM_AUDIT_URL: "https://audit.example"
+  hooks:
+    PreToolUse:
+      - command: "/opt/switchroom-audit.sh"
+        timeout: 5
+  # Bundled skills that ship with switchroom. `humanizer` removes AI-writing
+  # patterns from agent replies before they reach Telegram (29 patterns from
+  # Wikipedia's "Signs of AI writing" guide). `humanizer-calibrate` is its
+  # companion that builds a personal voice template from your message history.
+  # Remove from this list to disable. Per-agent `skills:` is unioned with
+  # this default — don't repeat shared skills in each agent.
+  skills: [humanizer, humanizer-calibrate]
+  # Optional: point the humanizer at a voice template generated by
+  # `/humanizer-calibrate`. Without this, falls back to generic rules.
+  # humanizer_voice_file: ~/.switchroom/voice.md
+  system_prompt_append: |
+    Always respond concisely.
+
+  # --- Default sub-agents ---
+  # Every agent gets these workers. They run on cheaper/faster models
+  # in the background so the main agent stays available for new requests.
+  # Override per-agent or per-profile by redefining the same name.
+  subagents:
+    worker:
+      description: "Handles implementation tasks: writing, editing, building, testing. Use for any task that takes more than a few seconds."
+      model: sonnet
+      background: true
+      # NOTE: `isolation: worktree` used to live here as a global default
+      # but moved to the `coding` profile in switchroom 0.6.6 (#682). It
+      # hard-failed for any agent whose cwd was not a git repo — i.e. the
+      # majority of switchroom agents, which run from
+      # `~/.switchroom/agents/<name>` with no git init. Worktree isolation
+      # is opt-in via `extends: coding` now. See CHANGELOG and #682.
+      # 100 turns is a comfortable budget for most worker tasks; if a
+      # worker exhausts this mid-flow, it'll be reported as #423-style
+      # ceiling. Bump to 200 for genuinely long PR-shipping flows or
+      # remove the line entirely to inherit Claude Code's default.
+      # Origin: this used to be 50 and was the literal cause of #423
+      # ("worker sub-agents hit ~50 tool-use ceiling mid-flow before
+      # finishing"). Don't shrink it without good reason.
+      maxTurns: 100
+      color: blue
+      disallowedTools:
+        - "mcp__switchroom-telegram__*"
+      prompt: |
+        You are a worker sub-agent. Implement the task described in your
+        prompt precisely and completely. Commit your work when done.
+        If requirements are ambiguous, state your assumptions rather
+        than guessing. Return a concise summary of what you did.
+    researcher:
+      description: "Explores codebases, reads documentation, searches for information. Use for any research or investigation task."
+      model: haiku
+      background: true
+      color: green
+      disallowedTools:
+        - "mcp__switchroom-telegram__*"
+      prompt: |
+        You are a research sub-agent. Investigate the topic described
+        in your prompt thoroughly. Return structured findings — not
+        raw file contents. Keep your report under 500 words unless
+        the parent explicitly asks for more detail.
+    reviewer:
+      description: "Reviews code, plans, documents for quality, correctness, and completeness. Use after a worker finishes or before shipping."
+      model: sonnet
+      color: purple
+      disallowedTools:
+        - "mcp__switchroom-telegram__*"
+      prompt: |
+        You are a review sub-agent. Examine the work described in
+        your prompt for correctness, completeness, security, and
+        quality. Report findings as a punch list: what's good, what
+        needs fixing, what's missing. Be rigorous but concise.
+
+# --- Named profiles (opt-in presets) ---
+# Agents inherit from a profile via `extends: <name>`.
+# Inline profiles here take priority over filesystem profiles/<name>/
+# (which can additionally bundle CLAUDE.md.hbs + skills/).
+profiles:
+  # The `coding` profile pairs with `profiles/coding/` on disk (which
+  # ships the CLAUDE.md template and skills). Its inline counterpart
+  # here carries the YAML-level defaults that the filesystem assets
+  # advertise — worktree-isolated workers chief among them. Agents
+  # whose cwd IS a git checkout (a real code repo) should
+  # `extends: coding` to pick this up. Agents whose cwd is the default
+  # `~/.switchroom/agents/<name>` (no git) should NOT — Claude Code
+  # cannot create a worktree off a non-repo and the worker will fail.
+  coding:
+    subagents:
+      worker:
+        isolation: worktree
+
+  coder:
+    tools:
+      allow: [Bash, Read, Write, Edit, Grep, Glob]
+    system_prompt_append: |
+      You write production-quality TypeScript. Prefer explicit types.
+    skills: [code-review, architecture]
+
+  advisor:
+    tools:
+      deny: [Bash, Edit, Write]
+    soul:
+      style: warm, empathetic, non-prescriptive
+      boundaries: not a licensed professional — always recommend consulting a qualified expert
+    system_prompt_append: |
+      Prioritize listening and asking clarifying questions.
+
+# --- Agents ---
+# Minimal per-agent declarations. Everything else inherited.
+agents:
+  coach:
+    topic_name: "Fitness"
+    topic_emoji: "🏋️"
+    extends: advisor                    # inherits from inline profile above
+    soul:
+      name: Coach
+      style: motivational, direct       # overrides advisor.soul.style
+    memory:
+      collection: fitness
+    schedule:
+      - cron: "0 8 * * *"
+        prompt: "Good morning check-in: ask about sleep, energy, and plans for today"
+      - cron: "0 20 * * 0"
+        prompt: "Weekly review: summarize this week's activity and progress"
+
+  dev:
+    topic_name: "Code"
+    topic_emoji: "💻"
+    extends: coder                      # inherits from inline profile above
+    model: claude-opus-4-7              # override defaults.model for this agent
+    memory:
+      collection: coding
+    cli_args: ["--effort", "high"]      # escape hatch: extra exec claude flags
+
+  assistant:
+    topic_name: "General"
+    topic_emoji: "💬"
+    memory:
+      collection: general
+    # No `extends:` → uses the "default" filesystem profile (profiles/default/)
+    # No tool/model overrides → inherits everything from defaults:
+
+  exec:
+    topic_name: "Executive"
+    topic_emoji: "📋"
+    extends: advisor
+    soul:
+      name: Friday
+      style: efficient, proactive, anticipates needs
+    skills: [daily-briefing, meeting-prep]
+    memory:
+      collection: executive
+    schedule:
+      - cron: "0 7 * * 1-5"
+        prompt: "Daily briefing: summarize today's calendar, pending tasks, and priorities"
+
+  # Example admin agent — its gateway intercepts fleet-management slash
+  # commands (/agents, /restart, /update, /logs, etc.) and runs them
+  # locally via the switchroom CLI instead of forwarding to Claude. Per-
+  # agent commands like /auth list, /auth reauth, /interrupt, /new work
+  # on every agent regardless of admin status. See the three-tier
+  # command model in docs/architecture.md.
+  #
+  # Uncomment after creating a second BotFather bot and adding its
+  # token to the vault (`switchroom vault set telegram-admin-bot-token`).
+  # admin:
+  #   topic_name: "Admin"
+  #   topic_emoji: "🛠️"
+  #   bot_token: "vault:telegram-admin-bot-token"
+  #   admin: true
+  #   system_prompt_append: |
+  #     You are the fleet admin agent. Always respond concisely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.7.15",
+  "version": "0.10.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": {
@@ -9,6 +9,7 @@
   "main": "./dist/cli/switchroom.js",
   "files": [
     "dist",
+    "examples",
     "profiles",
     "skills",
     "telegram-plugin",
@@ -20,13 +21,15 @@
     "dev": "bun bin/switchroom.ts",
     "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",
-    "test": "vitest run && bun test telegram-plugin/tests/history.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/foreman-state.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/tests/turns-writer.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",
+    "test": "vitest run && bun test telegram-plugin/tests/history.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/tests/turns-writer.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",
     "test:vitest": "vitest run",
-    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts 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-passphrase-attest.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/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/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/setup-state.test.ts telegram-plugin/tests/history.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/foreman-state.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/tests/turns-writer.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts",
+    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts 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/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/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/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/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/tests/turns-writer.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/uat/load-env.test.ts",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs",
+    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs",
     "lint:tsc": "tsc --noEmit",
     "lint:plugin-references": "node scripts/check-plugin-references.mjs",
+    "lint:bot-api-wrapping": "bash scripts/check-bot-api-wrapping.sh",
+    "lint:bun-test-imports": "node scripts/check-bun-test-imports.mjs",
     "prepublishOnly": "npm run build && npm run lint && npm test"
   },
   "dependencies": {

package/profiles/_base/settings.json.hbs

@@ -1,15 +1,30 @@
+{{!--
+  Two keys deliberately omitted from this template (do not re-add):
+
+  * `skipDangerousModePermissionPrompt` — real key, but Claude Code IGNORES it
+    in project-level .claude/settings.json as a security measure (only user
+    or local scope is honored). It also belongs under `permissions.`, not
+    top-level. autoaccept (src/agents/autoaccept.ts) handles the prompt instead.
+    See https://code.claude.com/docs/en/settings (permissions section).
+
+  * `enabledPlugins` — REDUNDANT, not nonfunctional. Plugin selection is
+    driven at the CLI by profiles/_base/start.sh.hbs (`--channels
+    plugin:telegram@claude-plugins-official` in vanilla mode, or
+    `--dangerously-load-development-channels server:switchroom-telegram` in
+    vendored-plugin mode). Re-adding an `enabledPlugins` block here would
+    work but duplicate state with the CLI flag and risk drift.
+
+  A `settings_raw` block in switchroom.yaml CAN still inject either key via
+  the deep-merge escape hatch (src/config/merge.ts) — that's intentional
+  power-user territory, not a regression.
+--}}
 {
   "permissions": {
     "allow": {{{json permissionAllow}}},
     "deny": {{{json toolsDeny}}}{{#if defaultModeAcceptEdits}},
     "defaultMode": "acceptEdits"{{/if}}
-  },
-  "enabledPlugins": {
-    "telegram@claude-plugins-official": {{#if useSwitchroomPlugin}}false{{else}}true{{/if}}
   }{{#if hindsightEnabled}},
   "autoMemoryEnabled": false{{/if}}{{#if mcpServers}},
   "mcpServers": {{{json mcpServers}}}
-  {{/if}}{{#if skipPermissionPrompt}},
-  "skipDangerousModePermissionPrompt": true
   {{/if}}
 }