@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/hermes_cli/telegram_managed_bot.py

@@ -0,0 +1,358 @@
+"""Telegram Managed Bot onboarding client.
+
+Uses Telegram's Managed Bots feature to create a user-owned child bot without
+manual BotFather token copy-paste. Hermes talks only to the Nous onboarding
+service; the raw Telegram token is saved locally after one-time retrieval.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+import sys
+import time
+import urllib.parse
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+# Default pairing API base URL (Nous-hosted Cloudflare Worker).
+# Override for PoC/staging with TELEGRAM_ONBOARDING_URL.
+DEFAULT_API_URL = "https://setup.hermes-agent.nousresearch.com"
+TELEGRAM_ONBOARDING_URL_ENV = "TELEGRAM_ONBOARDING_URL"
+
+# The Nous-hosted manager bot username (without @). The backend returns the
+# actual deep link, so this is only used by local helpers/tests.
+DEFAULT_MANAGER_BOT = "HermesSetupBot"
+
+DEFAULT_BOT_NAME = "Hermes Agent"
+DEFAULT_POLL_TIMEOUT = 180
+POLL_INTERVAL = 2
+
+_USERNAME_SLUG_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567"
+_TELEGRAM_BOT_TOKEN_RE = re.compile(r"^\d+:[A-Za-z0-9_-]{30,}$")
+
+
+@dataclass(frozen=True)
+class TelegramPairing:
+    """Pairing record returned by the Telegram onboarding service."""
+
+    pairing_id: str
+    poll_token: str
+    suggested_username: str
+    deep_link: str
+    qr_payload: str
+    expires_at: str | None = None
+
+
+@dataclass(frozen=True)
+class TelegramBotSetupResult:
+    """Successful Telegram onboarding result returned by the setup service."""
+
+    token: str
+    bot_username: str | None = None
+    owner_user_id: int | None = None
+
+
+def _api_url(api_url: str | None = None) -> str:
+    """Resolve the onboarding API URL, honoring the PoC env override."""
+    return (
+        api_url or os.environ.get(TELEGRAM_ONBOARDING_URL_ENV) or DEFAULT_API_URL
+    ).rstrip("/")
+
+
+def is_valid_telegram_bot_token(token: object) -> bool:
+    """Return True when *token* has Telegram's bot-token shape."""
+    return isinstance(token, str) and bool(_TELEGRAM_BOT_TOKEN_RE.match(token))
+
+
+def _parse_owner_user_id(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    if isinstance(value, str) and value.isdecimal():
+        parsed = int(value)
+        return parsed if parsed > 0 else None
+    return None
+
+
+def render_qr_terminal(url: str) -> str:
+    """Render a URL as a QR code string suitable for terminal output."""
+    try:
+        import io
+
+        import qrcode  # type: ignore[import-untyped]
+
+        qr = qrcode.QRCode(
+            version=None,
+            error_correction=qrcode.constants.ERROR_CORRECT_L,
+            box_size=1,
+            border=1,
+        )
+        qr.add_data(url)
+        qr.make(fit=True)
+
+        buf = io.StringIO()
+        qr.print_ascii(out=buf, invert=True)
+        return buf.getvalue()
+    except ImportError:
+        return ""
+
+
+def print_qr_code(url: str, *, include_link: bool = True) -> None:
+    """Print a QR code to stdout, with URL fallback if qrcode is missing."""
+    qr_text = render_qr_terminal(url)
+    if qr_text:
+        print(qr_text)
+    else:
+        print("  (Install 'qrcode' for a scannable QR code: pip install qrcode)")
+    if include_link:
+        print(f"  Link: {url}")
+
+
+def generate_username_slug(length: int = 16) -> str:
+    """Generate a base32-ish slug for Telegram username correlation.
+
+    Sixteen characters from a 32-symbol alphabet gives 80 bits of entropy while
+    keeping ``hermes_<slug>_bot`` under Telegram's 32-character username limit.
+    """
+    return "".join(secrets.choice(_USERNAME_SLUG_ALPHABET) for _ in range(length))
+
+
+def generate_bot_username(profile_name: Optional[str] = None) -> str:
+    """Generate a secure suggested bot username like ``hermes_<slug>_bot``.
+
+    ``profile_name`` is accepted for backward compatibility with the original
+    PoC, but is intentionally not embedded in the username. The username has to
+    carry enough entropy for backend correlation.
+    """
+    _ = profile_name
+    return f"hermes_{generate_username_slug()}_bot"
+
+
+def generate_deep_link(
+    manager_bot: str = DEFAULT_MANAGER_BOT,
+    suggested_username: Optional[str] = None,
+    suggested_name: Optional[str] = None,
+) -> str:
+    """Build a ``t.me/newbot`` deep link for managed bot creation."""
+    manager = manager_bot.lstrip("@")
+    username = suggested_username or generate_bot_username()
+    base_url = (
+        "https://t.me/newbot/"
+        f"{urllib.parse.quote(manager)}/"
+        f"{urllib.parse.quote(username)}"
+    )
+
+    if suggested_name:
+        params = urllib.parse.urlencode({"name": suggested_name})
+        return f"{base_url}?{params}"
+    return base_url
+
+
+def generate_pairing_nonce() -> str:
+    """Generate a legacy-compatible random nonce string.
+
+    The new protocol uses service-created ``pairing_id`` + bearer
+    ``poll_token`` instead of a path nonce, but this helper is harmless and
+    still useful for callers/tests that need a generic random id.
+    """
+    return secrets.token_hex(16)
+
+
+def create_pairing(
+    api_url: str | None = None,
+    bot_name: str = DEFAULT_BOT_NAME,
+    timeout: float = 10.0,
+) -> TelegramPairing | None:
+    """Create a Telegram onboarding pairing.
+
+    ``POST /v1/telegram/pairings`` returns the deep link, QR payload, public
+    pairing id, and secret poll token. The token is only used as a bearer
+    credential while polling.
+    """
+    try:
+        resp = httpx.post(
+            f"{_api_url(api_url)}/v1/telegram/pairings",
+            json={"bot_name": bot_name},
+            timeout=timeout,
+        )
+        if resp.status_code not in (200, 201):
+            return None
+        data = resp.json()
+    except (httpx.HTTPError, ValueError):
+        return None
+
+    required = ("pairing_id", "poll_token", "suggested_username", "deep_link")
+    if not all(isinstance(data.get(key), str) and data.get(key) for key in required):
+        return None
+
+    qr_payload = data.get("qr_payload") or data["deep_link"]
+    if not isinstance(qr_payload, str):
+        return None
+
+    expires_at = data.get("expires_at")
+    return TelegramPairing(
+        pairing_id=data["pairing_id"],
+        poll_token=data["poll_token"],
+        suggested_username=data["suggested_username"],
+        deep_link=data["deep_link"],
+        qr_payload=qr_payload,
+        expires_at=expires_at if isinstance(expires_at, str) else None,
+    )
+
+
+def poll_pairing_result_once(
+    api_url: str | None,
+    pairing: TelegramPairing,
+    timeout: float = 10.0,
+) -> TelegramBotSetupResult | None:
+    """Poll the onboarding service once. Returns setup metadata when ready."""
+    resp = httpx.get(
+        f"{_api_url(api_url)}/v1/telegram/pairings/{pairing.pairing_id}",
+        headers={"Authorization": f"Bearer {pairing.poll_token}"},
+        timeout=timeout,
+    )
+    if resp.status_code != 200:
+        return None
+
+    data = resp.json()
+    if data.get("status") != "ready":
+        return None
+    token = data.get("token")
+    if not is_valid_telegram_bot_token(token):
+        return None
+
+    bot_username = data.get("bot_username")
+    return TelegramBotSetupResult(
+        token=token,
+        bot_username=bot_username
+        if isinstance(bot_username, str) and bot_username
+        else None,
+        owner_user_id=_parse_owner_user_id(data.get("owner_user_id")),
+    )
+
+
+def poll_pairing_once(
+    api_url: str | None,
+    pairing: TelegramPairing,
+    timeout: float = 10.0,
+) -> str | None:
+    """Poll the onboarding service once. Returns the token when ready."""
+    result = poll_pairing_result_once(api_url, pairing, timeout=timeout)
+    return result.token if result else None
+
+
+def poll_for_setup_result(
+    api_url: str | None,
+    pairing: TelegramPairing,
+    timeout: float = DEFAULT_POLL_TIMEOUT,
+    interval: float = POLL_INTERVAL,
+) -> Optional[TelegramBotSetupResult]:
+    """Poll the pairing API until setup metadata is available or timeout."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            result = poll_pairing_result_once(api_url, pairing)
+            if result:
+                return result
+        except (httpx.HTTPError, ValueError):
+            pass
+        time.sleep(interval)
+    return None
+
+
+def poll_for_token(
+    api_url: str | None,
+    pairing: TelegramPairing,
+    timeout: float = DEFAULT_POLL_TIMEOUT,
+    interval: float = POLL_INTERVAL,
+) -> Optional[str]:
+    """Poll the pairing API until the bot token is available or timeout."""
+    result = poll_for_setup_result(api_url, pairing, timeout=timeout, interval=interval)
+    return result.token if result else None
+
+
+def auto_setup_telegram_bot_result(
+    api_url: str | None = None,
+    manager_bot: str = DEFAULT_MANAGER_BOT,
+    profile_name: Optional[str] = None,
+    poll_timeout: float = DEFAULT_POLL_TIMEOUT,
+) -> Optional[TelegramBotSetupResult]:
+    """Run the full automatic Telegram bot creation flow."""
+    _ = manager_bot, profile_name
+    resolved_api_url = _api_url(api_url)
+    print()
+    print(f"  Contacting Hermes Telegram onboarding service: {resolved_api_url}")
+    sys.stdout.flush()
+    pairing = create_pairing(resolved_api_url)
+    if not pairing:
+        print("  ✗ Could not reach the Hermes Telegram onboarding service.")
+        print("    Try the manual setup instead, or check your network.")
+        return None
+
+    print("  ✓ Pairing created")
+    print("  Rendering QR code...")
+    sys.stdout.flush()
+    print()
+    print("  Scan this QR code with your phone, or open the link below:")
+    print()
+    print_qr_code(pairing.qr_payload, include_link=False)
+    print()
+    print(f"  Link: {pairing.deep_link}")
+    print()
+    print("  When Telegram opens, tap 'Create Bot' to confirm.")
+    print("  (You can edit the bot display name before confirming)")
+    print()
+
+    spinner_chars = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    start = time.monotonic()
+    deadline = start + poll_timeout
+    idx = 0
+
+    while time.monotonic() < deadline:
+        char = spinner_chars[idx % len(spinner_chars)]
+        elapsed = int(time.monotonic() - start)
+        remaining = max(0, int(poll_timeout - elapsed))
+        sys.stdout.write(
+            f"\r  {char} Waiting for bot creation... ({remaining}s remaining) "
+        )
+        sys.stdout.flush()
+        idx += 1
+
+        try:
+            result = poll_pairing_result_once(resolved_api_url, pairing)
+            if result:
+                sys.stdout.write(
+                    "\r  ✓ Bot created successfully!                              \n"
+                )
+                sys.stdout.flush()
+                return result
+        except (httpx.HTTPError, ValueError):
+            pass
+        time.sleep(POLL_INTERVAL)
+
+    sys.stdout.write("\r  ✗ Timed out waiting for bot creation.                    \n")
+    sys.stdout.flush()
+    print("    The bot may still be created — check Telegram.")
+    print("    You can paste the token manually below, or re-run setup.")
+    return None
+
+
+def auto_setup_telegram_bot(
+    api_url: str | None = None,
+    manager_bot: str = DEFAULT_MANAGER_BOT,
+    profile_name: Optional[str] = None,
+    poll_timeout: float = DEFAULT_POLL_TIMEOUT,
+) -> Optional[str]:
+    """Run automatic Telegram bot creation and return only the bot token."""
+    result = auto_setup_telegram_bot_result(
+        api_url=api_url,
+        manager_bot=manager_bot,
+        profile_name=profile_name,
+        poll_timeout=poll_timeout,
+    )
+    return result.token if result else None

package/agent/hermes_cli/tips.py

@@ -298,7 +298,7 @@ TIPS = [
     "Any website can expose skills via /.well-known/skills/index.json — the skills hub discovers them automatically.",
     "The skills audit log at ~/.hermes/skills/.hub/audit.log tracks every install and removal operation.",
     "Stale git worktrees are auto-cleaned: 24-72h old with no unpushed commits get pruned on startup.",
-    "Each profile gets its own subprocess HOME at HERMES_HOME/home/ — isolated git, ssh, npm, gh configs.",
+    "Profiles scope Hermes state via HERMES_HOME; host tool subprocesses keep your real HOME unless terminal.home_mode is profile.",
     "HERMES_HOME_MODE env var (octal, e.g. 0701) sets custom directory permissions for web server traversal.",
     "Container mode: place .container-mode in HERMES_HOME and the host CLI auto-execs into the container.",
     "Ctrl+C has 5 priority tiers: cancel recording → cancel prompts → cancel picker → interrupt agent → exit.",
@@ -345,7 +345,7 @@ TIPS = [
     '/copy [N] copies the last assistant response to your clipboard, or the Nth-from-last with a number.',
     '/redraw forces a full UI repaint, fixing terminal drift after tmux resize or mouse selection artifacts.',
     '/agents (alias /tasks) shows active agents and running background tasks across the current session.',
-    '/footer toggles the gateway footer on final replies showing model, tool counts, and turn timing.',
+    '/footer toggles the gateway footer on final replies showing model, context %, and cwd.',
     '/busy queue|steer|interrupt controls what pressing Enter does while Hermes is working.',
     '/topic in Telegram DMs enables user-managed multi-session topic mode — /topic <id> restores past sessions inline.',
     '/approve session|always runs a pending dangerous command with your chosen trust scope; /deny rejects it.',
@@ -381,7 +381,7 @@ TIPS = [
     'Ctrl+G or Ctrl+X Ctrl+E in the TUI opens the input buffer in $EDITOR for long multi-line prompts.',
     'The TUI renders LaTeX inline — $E=mc^2$ becomes Unicode math instead of raw TeX.',
     'hermes dashboard launches a local web UI at 127.0.0.1:9119 — zero data leaves localhost.',
-    'hermes dashboard --tui embeds the full Hermes TUI in your browser via xterm.js and a WebSocket PTY.',
+    'hermes dashboard embeds the full Hermes TUI in your browser via xterm.js and a WebSocket PTY.',
     'Drop a YAML in ~/.hermes/dashboard-themes/ with two palette colors to reskin the entire dashboard.',
     'Dashboard plugins are drop-in: manifest.json + JS bundle in ~/.hermes/dashboard-plugins/ — no npm build required.',
     'layoutVariant: cockpit in a dashboard theme adds a 260px left rail that plugins can populate via the sidebar slot.',
@@ -484,4 +484,3 @@ def get_random_tip(exclude_recent: int = 0) -> str:
             deduplication across sessions.
     """
     return random.choice(TIPS)
-

package/agent/hermes_cli/tools_config.py

@@ -73,7 +73,6 @@ CONFIGURABLE_TOOLSETS = [
     ("clarify",         "❓ Clarifying Questions",      "clarify"),
     ("delegation",      "👥 Task Delegation",           "delegate_task"),
     ("cronjob",         "⏰ Cron Jobs",                 "create/list/update/pause/resume/run, with optional attached skills"),
-    ("messaging",       "📨 Cross-Platform Messaging",  "send_message"),
     ("homeassistant",    "🏠 Home Assistant",           "smart home device control"),
     ("spotify",          "🎵 Spotify",                  "playback, search, playlists, library"),
     ("discord",         "💬 Discord (read/participate)", "fetch messages, search members, create thread"),
@@ -82,6 +81,22 @@ CONFIGURABLE_TOOLSETS = [
     ("computer_use",     "🖱️  Computer Use (macOS)",     "background desktop control via cua-driver"),
 ]
 
+
+def gui_toolset_label(label: str) -> str:
+    """Strip leading emoji/icons from toolset titles for GUI surfaces.
+
+    Registry labels use ``<emoji> <title>``; plugin toolsets prefix with ``🔌``.
+    CLI/TUI keeps the raw ``label`` — only HTTP APIs call this helper.
+    """
+    text = (label or "").strip()
+    if not text:
+        return text
+    parts = text.split(None, 1)
+    if len(parts) == 2 and parts[0] and not any(ch.isascii() and ch.isalnum() for ch in parts[0]):
+        return parts[1].strip()
+    return text
+
+
 # Toolsets that are OFF by default for new installs.
 # They're still in _HERMES_CORE_TOOLS (available at runtime if enabled),
 # but the setup checklist won't pre-select them for first-time users.
@@ -181,6 +196,30 @@ def _get_plugin_toolset_keys() -> set:
     except Exception:
         return set()
 
+
+def _checklist_toolset_keys(platform: str) -> Set[str]:
+    """Return the toolset keys the ``hermes tools`` checklist actually offers
+    for ``platform``.
+
+    This mirrors exactly what ``_prompt_toolset_checklist`` renders:
+    ``_get_effective_configurable_toolsets()`` (built-in + plugin toolsets),
+    filtered by ``_toolset_allowed_for_platform``. The checklist's returned
+    selection can therefore only ever be a subset of this universe.
+
+    Non-configurable toolsets that ``_get_platform_tools`` resolves at read
+    time — ``kanban`` and other check_fn-gated toolsets, recovered platform
+    composites, MCP server names — are NOT in this set because the checklist
+    never shows them. Use this to scope the added/removed diff the UI prints,
+    so ``hermes tools`` never claims to add or remove a toolset the user was
+    never given a checkbox for. The underlying config is unaffected — those
+    entries are preserved by ``_save_platform_tools`` regardless.
+    """
+    return {
+        ts_key
+        for ts_key, _, _ in _get_effective_configurable_toolsets()
+        if _toolset_allowed_for_platform(ts_key, platform)
+    }
+
 # Platform display config — derived from the canonical registry so every
 # module shares the same data.  Kept as dict-of-dicts for backward
 # compatibility with existing ``PLATFORMS[key]["label"]`` access patterns.
@@ -202,6 +241,13 @@ TOOL_CATEGORIES = {
         "name": "Text-to-Speech",
         "icon": "🔊",
         "providers": [
+            {
+                "name": "Microsoft Edge TTS",
+                "badge": "★ recommended · free",
+                "tag": "Good quality, no API key needed",
+                "env_vars": [],
+                "tts_provider": "edge",
+            },
             {
                 "name": "Nous Subscription",
                 "badge": "subscription",
@@ -212,13 +258,6 @@ TOOL_CATEGORIES = {
                 "managed_nous_feature": "tts",
                 "override_env_vars": ["VOICE_TOOLS_OPENAI_KEY", "OPENAI_API_KEY"],
             },
-            {
-                "name": "Microsoft Edge TTS",
-                "badge": "★ recommended · free",
-                "tag": "Good quality, no API key needed",
-                "env_vars": [],
-                "tts_provider": "edge",
-            },
             {
                 "name": "OpenAI TTS",
                 "badge": "paid",
@@ -406,15 +445,26 @@ TOOL_CATEGORIES = {
         # Per-provider rows for Browserbase, Browser Use, and Firecrawl are
         # injected at runtime from plugins.browser.<vendor>.provider via
         # _plugin_browser_providers() in _visible_providers(). Only
-        # non-provider UX setup-flow rows remain here:
+        # non-provider UX setup-flow rows remain here. "Local Browser" is
+        # listed FIRST so it is the default-highlighted (index 0) choice on a
+        # fresh install — pressing Enter must land on the free, no-key local
+        # backend, never on the paid Nous Subscription gateway row:
+        #   - "Local Browser" — non-cloud option, no CloudBrowserProvider.
         #   - "Nous Subscription (Browser Use cloud)" — managed Browser Use
         #     billed via Nous subscription (requires_nous_auth +
         #     override_env_vars). Uses the browser-use plugin as the
         #     underlying backend but has a distinct setup UX.
-        #   - "Local Browser" — non-cloud option, no CloudBrowserProvider.
         #   - "Camofox" — anti-detection local Firefox; short-circuits the
         #     cloud-provider dispatch path via _is_camofox_mode().
         "providers": [
+            {
+                "name": "Local Browser",
+                "badge": "★ recommended · free",
+                "tag": "Headless Chromium, no API key needed",
+                "env_vars": [],
+                "browser_provider": "local",
+                "post_setup": "agent_browser",
+            },
             {
                 "name": "Nous Subscription (Browser Use cloud)",
                 "badge": "subscription",
@@ -426,14 +476,6 @@ TOOL_CATEGORIES = {
                 "override_env_vars": ["BROWSER_USE_API_KEY"],
                 "post_setup": "agent_browser",
             },
-            {
-                "name": "Local Browser",
-                "badge": "★ recommended · free",
-                "tag": "Headless Chromium, no API key needed",
-                "env_vars": [],
-                "browser_provider": "local",
-                "post_setup": "agent_browser",
-            },
             {
                 "name": "Camofox",
                 "badge": "free · local",
@@ -803,14 +845,17 @@ def _run_post_setup(post_setup_key: str):
             # batch shims).  On POSIX npm_bin is the plain path — same
             # behaviour as before.
             result = subprocess.run(
-                [npm_bin, "install", "--silent"],
+                # --workspaces=false restricts the install to the repo root
+                # only, avoiding the apps/* glob which would pull in
+                # apps/desktop (Electron + node-pty) unnecessarily. See #38772.
+                [npm_bin, "install", "--silent", "--workspaces=false"],
                 capture_output=True, text=True, cwd=str(PROJECT_ROOT)
             )
             if result.returncode == 0:
                 _print_success("    Node.js dependencies installed")
             else:
                 from hermes_constants import display_hermes_home
-                _print_warning(f"    npm install failed - run manually: cd {display_hermes_home()}/hermes-agent && npm install")
+                _print_warning(f"    npm install failed - run manually: cd {display_hermes_home()}/hermes-agent && npm install --workspaces=false")
                 if result.stderr:
                     _print_info(f"      {result.stderr.strip()[:200]}")
         elif not node_modules.exists():
@@ -908,13 +953,14 @@ def _run_post_setup(post_setup_key: str):
             import subprocess
             # Absolute npm path so .cmd shim executes on Windows.
             result = subprocess.run(
-                [_npm_bin, "install", "--silent"],
+                # --workspaces=false avoids resolving apps/desktop. See #38772.
+                [_npm_bin, "install", "--silent", "--workspaces=false"],
                 capture_output=True, text=True, cwd=str(PROJECT_ROOT)
             )
             if result.returncode == 0:
                 _print_success("    Camofox installed")
             else:
-                _print_warning("    npm install failed - run manually: npm install")
+                _print_warning("    npm install failed - run manually: npm install --workspaces=false")
         if camofox_dir.exists():
             _print_info("    Start the Camofox server:")
             _print_info("      npx @askjo/camofox-browser")
@@ -1125,6 +1171,68 @@ def _run_post_setup(post_setup_key: str):
             _print_info("    xAI will remain inactive until credentials are configured.")
 
 
+def valid_post_setup_keys() -> Set[str]:
+    """Return the set of post-setup keys declared by any visible provider.
+
+    Collected from ``TOOL_CATEGORIES`` plus the plugin-registered web /
+    image-gen / video-gen / browser providers (which can also carry a
+    ``post_setup``). This is the allowlist the ``hermes tools post-setup``
+    command and the dashboard post-setup endpoint validate against, so a
+    caller can't drive ``_run_post_setup`` with an arbitrary key.
+    """
+    keys: Set[str] = set()
+    for cat in TOOL_CATEGORIES.values():
+        for prov in cat.get("providers", []):
+            ps = prov.get("post_setup")
+            if ps:
+                keys.add(ps)
+    # Plugin-registered providers can declare their own post_setup hooks.
+    for builder in (
+        _plugin_web_search_providers,
+        _plugin_image_gen_providers,
+        _plugin_video_gen_providers,
+        _plugin_browser_providers,
+    ):
+        try:
+            for prov in builder():
+                ps = prov.get("post_setup")
+                if ps:
+                    keys.add(ps)
+        except Exception:  # pragma: no cover — defensive; plugins optional
+            continue
+    return keys
+
+
+def run_post_setup_command(args) -> int:
+    """``hermes tools post-setup <key>`` — non-interactive post-setup runner.
+
+    Runs the install/bootstrap hook a provider declares (npm install for
+    browser/Camofox, pip install for kittentts/piper/ddgs, cua-driver fetch,
+    etc.). This is the stable, scriptable target the dashboard spawns so the
+    GUI can drive backend setup without re-implementing the install logic.
+    Returns a process exit code (0 ok, 2 unknown key).
+    """
+    key = getattr(args, "post_setup_key", None)
+    if not key:
+        _print_error("Usage: hermes tools post-setup <key>")
+        return 2
+    valid = valid_post_setup_keys()
+    if key not in valid:
+        _print_error(
+            f"Unknown post-setup key: {key!r}. "
+            f"Valid keys: {', '.join(sorted(valid)) or '(none)'}"
+        )
+        return 2
+    _print_info(f"Running post-setup hook: {key}")
+    try:
+        _run_post_setup(key)
+    except Exception as exc:  # pragma: no cover — defensive
+        _print_error(f"Post-setup failed: {exc}")
+        return 1
+    _print_success(f"Post-setup '{key}' complete")
+    return 0
+
+
 # ─── Platform / Toolset Helpers ───────────────────────────────────────────────
 
 def _get_enabled_platforms() -> List[str]:
@@ -1328,6 +1436,10 @@ def _get_platform_tools(
             continue
         if ts_def.get("includes"):
             continue
+        # Posture toolsets (e.g. ``coding``) are session-level selections made
+        # by agent/coding_context.py — not per-platform capabilities to recover.
+        if ts_def.get("posture"):
+            continue
         ts_tools = set(resolve_toolset(ts_key))
         if not ts_tools or not ts_tools.issubset(platform_tool_universe):
             continue
@@ -3314,8 +3426,15 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
             # Show checklist
             new_enabled = _prompt_toolset_checklist(pinfo["label"], checklist_preselected, pkey)
 
-            added = new_enabled - current_enabled
-            removed = current_enabled - new_enabled
+            # Only diff against toolsets the checklist actually offered. The
+            # resolved ``current_enabled`` can include non-configurable toolsets
+            # (e.g. ``kanban``, recovered platform composites) the user was
+            # never shown a checkbox for; without this scope the summary would
+            # print spurious ``- kanban`` removals even though the config keeps
+            # them. See _checklist_toolset_keys.
+            _diff_universe = _checklist_toolset_keys(pkey)
+            added = (new_enabled - current_enabled) & _diff_universe
+            removed = (current_enabled - new_enabled) & _diff_universe
             if added:
                 for ts in sorted(added):
                     label = next((l for k, l, _ in _get_effective_configurable_toolsets() if k == ts), ts)
@@ -3424,8 +3543,12 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
             if new_enabled != all_current:
                 for pk in platform_keys:
                     prev = _get_platform_tools(config, pk, include_default_mcp_servers=False)
-                    added = new_enabled - prev
-                    removed = prev - new_enabled
+                    # Scope the printed diff to the checklist's universe (see
+                    # _checklist_toolset_keys) so non-configurable toolsets like
+                    # ``kanban`` aren't reported as added/removed.
+                    _diff_universe = _checklist_toolset_keys(pk)
+                    added = (new_enabled - prev) & _diff_universe
+                    removed = (prev - new_enabled) & _diff_universe
                     pinfo_inner = PLATFORMS[pk]
                     if added or removed:
                         print(color(f"  {pinfo_inner['label']}:", Colors.DIM))
@@ -3471,8 +3594,12 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
         )
 
         if new_enabled != current_enabled:
-            added = new_enabled - current_enabled
-            removed = current_enabled - new_enabled
+            # Scope the printed diff to the checklist's universe (see
+            # _checklist_toolset_keys) so non-configurable toolsets like
+            # ``kanban`` aren't reported as added/removed.
+            _diff_universe = _checklist_toolset_keys(pkey)
+            added = (new_enabled - current_enabled) & _diff_universe
+            removed = (current_enabled - new_enabled) & _diff_universe
 
             if added:
                 for ts in sorted(added):