feat(connections): add profile-safe connection health foundation

[Joeywrz]

What does this PR do?

Adds the generic core foundation needed by a Connections-style Desktop plugin without adding that product UI or any product-specific integration to Hermes core.

Hermes already knows which messaging platforms and MCP servers are configured, but Desktop plugins had no passive way to consume truthful MCP runtime health. The existing MCP test path is active: it can connect, probe, or enter authentication flows. Connection-health consumers also need a narrow contribution contract so the host can enforce stable provider identity, a fixed result shape, and non-executable repair kinds/routes.

This PR therefore adds two small core surfaces:

1. mcp.servers.status, a profile-scoped gateway RPC that projects configured servers plus cached runtime state without connecting to or probing them. This projection uses a credential-safe field whitelist and fixed failure messages.
2. connections.health, a Desktop SDK contribution area whose provider identity, result shape, and repair intents are normalized and validated by the host. Provider-authored display strings remain provider responsibility; the SDK does not claim to inspect arbitrary text for embedded secrets.

The approach keeps existing Hermes registries and configuration as the source of truth. The actual Connections UI and local API checks remain a standalone plugin, which is also the real consumer used for manual verification.

This supersedes the closed foundation draft #102567. That PR was withdrawn while the backend/SDK work was being reconsidered with the finished plugin; after product review, the scope decision changed to submit the generic core separately in three clean commits while keeping the product plugin outside this PR.

Related Issue

N/A — no issue describes this exact combination of a passive Desktop RPC and a generic connection-health contribution contract.

Related and historical work reviewed:

• feat(connections): expose passive profile-scoped health #102567 is the closed predecessor; this PR supersedes it with a cleaned commit series, provider-contract documentation, and the clarified core-only scope above.
• feat(gateway): expose read-only MCP server connection status #96977 exposes read-only MCP status through the authenticated HTTP API; this PR provides the profile-aware gateway JSON-RPC surface used by Desktop plugins.
• fix(mcp): isolate runtime ownership by profile #80746 and fix(mcp): make discovery lifecycle profile-scoped #99923 address broader profile ownership and discovery lifecycle concerns; this PR does not replace those larger changes and limits its scope to safe status projection.
• fix(mcp): suppress interactive OAuth in desktop probes #78604 suppresses interactive OAuth inside the existing active Desktop test endpoint; this PR avoids that test endpoint entirely for passive status reads.
• fix(mcp): report lazily registered servers as lazy, not configured or failed #100648 improves lazy-server status semantics; that status work is complementary to this consumer-facing RPC.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/mcp_tool_discovery.py, tools/mcp_tool_errors.py, and tools/mcp_tool_lifecycle.py
  • project cached MCP runtime state into a credential-safe status shape;
  • preserve the machine-readable auth_required / check_failed reason across existing string, copy, and pickle consumers;
  • scope connecting and failed runtime observations to their owning profile.
• tui_gateway/methods_tools.py
  • add the passive mcp.servers.status RPC;
  • inject the already-resolved profile configuration instead of invoking plugin discovery, secret hydration, OAuth, or MCP connection paths;
  • whitelist response fields and replace unexpected exceptions with a fixed message.
• apps/desktop/src/contrib/connection-health.ts and SDK exports
  • add the connections.health provider contract;
  • attach host provenance and stable contribution IDs;
  • accept only callable loaders and the supported non-executable message or internal /... route repair forms;
  • normalize the returned structure while leaving provider-authored display-string content under the provider's responsibility;
  • keep the React hook referentially stable across unrelated renders.
• Add focused MCP, profile, RPC, SDK, validation, and reference-stability regression tests.
• Document the Desktop provider contract, including its passivity and provider-content responsibilities.

How to Test

Run:

scripts/run_tests.sh tests/tools/test_mcp_tool.py tests/tools/test_mcp_lazy_start.py tests/tools/test_mcp_loop_profile_override.py tests/tui_gateway/test_mcp_profile_rpcs.py tests/gateway/test_multiplex_mcp_discovery.py tests/tools/test_mcp_bridge_single_failure.py
cd apps/desktop
npm run typecheck
npm run lint
npm run test:ui
npm run build

Verified after rebasing onto main 5a0b1ba766956a1a16bc2f17dc3b83eb63633402, on head 986ca92e2213fb07eda11ab09c6fe178577880c6:

• 145 affected Python tests passed, including real profile-config/RPC integration, multiplex runtime visibility and scoped shutdown cleanup. The scoped cleanup regression fails on the base.
• All 7,176 Desktop UI tests passed (719 files); the 16 contribution/SDK tests also passed separately.
• TypeScript typecheck and production Desktop build passed.
• ESLint passed with existing warnings and no errors; Ruff passed.
• scripts/check_compat_pointers.py, scripts/check-windows-footguns.py --diff origin/main and git diff --check passed.

The implementation follows the decomposed ownership: discovery/status in tools/mcp_tool_discovery.py, typed errors in tools/mcp_tool_errors.py, scoped cleanup in tools/mcp_tool_lifecycle.py. Tests import the owning modules directly. The passive RPC exposes named-profile runtime only when the multiplex runtime can scope it; it does not connect, probe, or hydrate credentials.

The standalone product plugin remains outside this PR. The repository-wide Python suite and native desktop platform suite were not rerun for this revision; no fresh native UI acceptance or GitHub Actions success is claimed.

Current GitHub status

After the update GitHub reports MERGEABLE against main 5a0b1ba766956a1a16bc2f17dc3b83eb63633402. Exact-head CI run is action_required; the external-fork workflows require maintainer approval. The PR remains BLOCKED pending repository gates, so conflict-free and locally tested does not yet mean CI-green or merge-ready.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched open and closed issues and PRs for overlapping MCP status, profile, OAuth-probe, and Desktop plugin work
• My PR contains only changes related to this feature (no standalone Connections plugin or Computer Use changes)
• I've run pytest tests/ -q and all tests pass — the full repository suite is not claimed; current affected-suite evidence is listed above
• I've added tests for my changes
• I've tested on my platform: macOS 26.6.2 (Apple Silicon / arm64)

Documentation & Housekeeping

• I've updated relevant documentation (website/docs/developer-guide/desktop-plugin-sdk.md)
• I've updated cli-config.yaml.example if I added/changed config keys — N/A, no config keys changed
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A, the SDK contract is documented in the developer guide
• I've considered cross-platform impact — no new platform APIs, paths, shell commands, or process-management behavior; the Windows footgun diff check passes
• I've updated tool descriptions/schemas if I changed tool behavior — N/A, no model tool changed; the new RPC and SDK contract are documented and tested

Screenshots / Logs

N/A — this PR adds framework surfaces and deliberately does not include the standalone Connections UI. The end-to-end consumer was verified locally and remains outside this core diff.