diff --git a/apps/desktop/README.md b/apps/desktop/README.md index 31cb679465..997cb72846 100644 --- a/apps/desktop/README.md +++ b/apps/desktop/README.md @@ -182,7 +182,9 @@ Changing profiles or connection modes is a soft workspace switch, not another cold boot. The shell and current management overlay remain mounted while gateway-bound nanostores are wiped, query-backed data is invalidated, and the new connection repopulates skeletons. This prevents rows or transcripts from -the previous gateway bleeding into the next one. +the previous gateway bleeding into the next one. Switching changes only the +foreground view and request route: it does not cancel turns or stop a backend, +and retained background sockets continue receiving events from running jobs. ### Verification diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md index 83d8d283ea..af9a488b87 100644 --- a/website/docs/user-guide/desktop.md +++ b/website/docs/user-guide/desktop.md @@ -302,9 +302,11 @@ Gateway connections are **machine-level**: the Gateways page manages which gatew Further down the same **Settings → Gateways** page, the connections registry manages a named list of every agent source the app knows about — the local runtime, any number of remote gateways (LAN, Tailscale, internet), Hermes Cloud instances, and SSH hosts — all persisted together in one place. You can jump there from the plug button at the right end of the sidebar profile rail (**Connect another Hermes gateway…**) or via **⌘K → Gateways**. The full guide, including the union agent roster, `@name-device` handles, fleet-wide updates, and the plugin SDK surface, is at [Connecting Desktop to Many Hermes Instances](./multi-connection-desktop.md). - **Every connection needs a unique name** (a device name such as "Homelab" or "Work laptop"). When the same profile name exists on several registered sources, surfaces disambiguate it as `@profile-device` (e.g. `@research-homelab`). +- **Switch sources from the Sessions sidebar.** The named selector appears when more than one source is registered; the adjacent profile rail then shows only that source's agents and remembers the last profile used there. - **Add / edit / remove / test** connections from the panel. The **Add** flow offers all four kinds — **Local**, **Hermes Cloud**, **Remote gateway**, and **SSH** (the Local button is disabled while the app-managed local entry exists, and a hint points cloud adds at the sign-in/discovery flow above). The local entry is managed by the app and cannot be removed. **Test** probes the connection's own HTTP and WebSocket legs directly. - **Duplicates are rejected at save time**: only one **local** entry ever; remote and cloud entries are deduplicated on the normalized URL (trimmed, trailing slashes stripped, lowercased — across both kinds); SSH entries on the normalized `user@host:port` plus remote profile. - Existing settings are **imported automatically** the first time you run a build with the registry: your current global connection and any legacy per-profile overrides become named entries. The legacy settings file is left untouched, so older builds keep working. +- Cloud entries come from the Hermes Cloud sign-in/discovery flow above, not from a hand-typed URL. - Tokens are stored encrypted with the OS keyring (with an explicit plain-text opt-in on keyring-less Linux). Side-by-side routing is live: each registered source dials its own backends and sockets on demand (keyed per connection + profile), the plugin SDK exposes the union agent roster (`host.agents()` / `host.ensureAgent()`), and **Update all instances** on the Gateways page dispatches `hermes update` to every eligible source at once — Hermes Cloud entries are skipped (the platform updates them), and each instance reports its own result. diff --git a/website/docs/user-guide/multi-connection-desktop.md b/website/docs/user-guide/multi-connection-desktop.md index 66d116a942..e712feb955 100644 --- a/website/docs/user-guide/multi-connection-desktop.md +++ b/website/docs/user-guide/multi-connection-desktop.md @@ -55,10 +55,10 @@ Rules worth knowing: - The **local** entry is managed by the app (it wears a **This device** pill) and cannot be removed. Removing any other connection tears down its live backends and tunnels; the instance itself is untouched. -- One connection is always the **Primary** (pill on its row): it owns the - app-managed window backend — boot overlay and install/update machinery. - **Make primary** on any row retargets that; removing the primary falls back - to the local entry. +- One connection is always the **Primary** (pill on its row): it is the + registry fallback for multi-source calls that do not name a source. + **Make primary** does not switch the current Sessions workspace; removing + the primary falls back to the local entry. - **Test** probes the connection's own HTTP *and* WebSocket legs, so a pass (the *"Reachable"* toast) means chat will actually work — not just that the host pinged. @@ -72,9 +72,10 @@ Rules worth knowing: the top of the Gateways page — the **Hermes Cloud** kind in the add-connection editor points you there. -As the pane's own caption notes: *"Chats and the agent roster follow the -source you pick; the app-managed window backend is still chosen by the -connection-mode controls above."* +Switch sources from the **Sessions** sidebar. Profiles, chats, messaging, and +cron stay scoped to that source; the app-managed window backend is still chosen +by the connection-mode controls above. **Primary** is the registry fallback and +does not switch the current workspace. ## Adding a connection, step by step @@ -154,27 +155,58 @@ keep streaming while you look at another source. ### Switching and scoping -Switching agents is the same gesture as switching profiles: +The sidebar foot follows one hierarchy: **source → profile → sessions**. +Sources are machines or hosted backends; profiles are isolated Hermes agents +that live on one source. -- **The profile rail** at the sidebar foot switches the active profile; the - home pill returns to the default profile and the layers pill shows the - **All profiles** view. **Cmd/Ctrl+1–9** switch profiles from the keyboard. -- The sidebar's session list, cron jobs, and messaging status are **scoped to - the active profile** — and, for agents on another source, to that source's - machine. Sessions you see under `@research-homelab` live on the Homelab; - its cron jobs run there; its messaging channels are the ones its gateway - hosts. The **All profiles** view merges every profile's sessions into one - list, with per-profile tags. +- With one registered source, no source control is added. Local-only Desktop + keeps the same profile rail and keyboard flow as before. +- With up to five sources, the sidebar shows direct source glyphs: a home for + **This device**, then stable initials for named sources. Larger registries + collapse into one source menu so profiles and actions are not crowded out. +- Selecting a source restores the last profile used there. The profile rail + then shows only that source's profiles; the home pill returns to its default + profile and the layers pill shows **All profiles on this source**. + **Cmd/Ctrl+1–9** continue to switch profiles within the active source. +- **This device** remains a first-class source even when a remote connection is + Primary. It can keep local sessions available during a remote outage, but the + app does not call it "offline mode": the selected model or tools may still + require internet access. +- The session list, messaging channels, cron jobs, settings, files, and memory + are all scoped to the active `(source, profile)`. Switching from a Telegram + source to a Signal source cannot leave the previous source's channel groups + or sessions in the sidebar. +- Merely displaying the switcher reads Electron's local connection registry. + Remote gateways are opened only when selected; there is no periodic fleet + polling. - Hovering an agent pre-warms its backend so the switch doesn't pay a cold boot. -- The **Capabilities** page (Skills / Tools / MCP) grows a matching scope: its +- The **Capabilities** page (Skills / Tools / MCP) has a matching scope: its **Configuring** selector lists every `(profile, device)` agent from the union roster, and picking one reads and writes **that machine's** skills, - toolsets, and MCP servers — no gateway switch. Hub installs, env keys, and - MCP setup all land on the selected agent's backend. (One caveat: the MCP - tab's *hot-reload into a live session* button only appears for agents on - the gateway your window is connected to; edits on other machines apply on - their next session.) + toolsets, and MCP servers without switching the Sessions workspace. Hub + installs, env keys, and MCP setup all land on the selected agent's backend. + The MCP tab's *hot-reload into a live session* button appears only for agents + on the gateway the window is connected to; edits on other machines apply on + their next session. + +Add, test, rename, or remove sources in **Settings → Connections**. The plug +button beside the profile actions is a shortcut to that single management +home, not a second add flow. + +### Sessions and Bot Mode + +Sessions intentionally show one active source at a time: this keeps files, +tools, channels, cron, and session history in one understandable execution +context. Bot Mode serves a different job and may present the union roster, +grouped by source, so a user can open one agent on a NAS and another on a VPS +from one surface. Opening a bot still activates its exact `(source, profile)` +route. + +Direct bot mentions and delegation remain source-local by default. Crossing a +backend boundary changes filesystem, credentials, tools, and trust context, so +cross-source execution should be an explicit bridge rather than an accidental +side effect of sharing one Desktop window. ## Updating every instance at once