docs(desktop): explain multi-source session scoping
This commit is contained in:
committed by
Teknium
parent
fa73b45d34
commit
4ea516b8d4
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user