Files
hermes-agent/apps/desktop/src/AGENTS.md
T
Siddharth Balyan 3b01b4ce0f feat(desktop): Nous free tier on Hermes Desktop (#105260)
* feat(desktop): free-tier state over RPC, status routes that name it, and a sign-in that keeps connectors

The desktop learns about the Nous free tier by reading local auth state (pull): free_tier.status
answers has_guest / enabled / carries_inference / notice_pending with zero network, and
free_tier.ack_notice persists the one-time notice flag on the identity itself. setup.runtime_check
reports free_tier for the selected route; /api/portal, the Nous card in /api/providers/oauth and
billing.state carry free_tier (billing answers the free tier locally instead of a portal call that
can only fail). The free-tier picker row carries an explicit free_tier_row flag and is never priced or
locked. POST /api/providers/oauth/nous/start over a free-tier identity registers the connector
transfer and returns its code and consent URL; the poller waits for the transfer before the token
grant, persists the account, runs settle_after_upgrade, and the poll response gains reason,
account_email and model.

* feat(desktop): free tier on Hermes Desktop: ready screen, notice strip, status chip, Billing view, one sign-in dialog

The renderer reads the free tier from free_tier.status (pull) into one store; the first-launch
intro is the same state rendered two ways, keyed on the backend's one-time flag: the onboarding
overlay opens on a ready screen when the free tier carries inference, else a one-time strip above
the composer. Settings > Billing gains a free_tier view (notice with one Sign in, Plan / Model /
Connectors summary, plan card, footnote; no payment or usage rows). A status-bar chip names the
tier and model while it carries inference. Every entry point opens one claimed sign-in dialog that
drives the extended oauth/nous route and maps the poll's status and reason to the ruled screens;
Done settles billing, model options, providers and re-homes a session still on nous/welcome. The
picker badge also fires on free_tier_row. Docs: Desktop section in the free-tier guide, AGENTS notes.

* fix(desktop): free_tier.status starts the free tier's background setup when no identity exists

A served backend has no session-setup moment like the CLI's, so beside an explicit provider the free
tier was never set up on the desktop: no connectors, no notice strip. The first status read now
starts the same one-attempt background setup; the call itself never waits.

* fix(desktop): one Sign in on the Billing page; Settings > Providers names the free tier, never Connected

The free-tier plan card is the what-you-get text alone (the notice carries the page's one Sign in).
The Nous provider row reads Nous · free tier with a Free tier tag while the identity is the free
tier, instead of Nous Portal · Connected.

* fix(desktop): Settings > Providers never files the free tier under Connected

* fix(desktop): the intro's shape is keyed on the route, not on the identity

free_tier.status reports available (an identity exists and the tier is on); whether inference
runs on the free tier is setup.runtime_check.free_tier, keyed on the resolved endpoint. The ready
screen shows when that route is the free tier; the composer strip when the user's own provider
carries inference. An own-key install used to get the ready screen.

* docs(desktop): say what the free-tier chip is keyed on

* fix(desktop): the featured Nous row's pitch on the free tier says what signing in adds

* fix(desktop): a cancelled or superseded sign-in attempt can no longer change the identity or hide the intro

Four lifecycle holes from review. The Nous poller checks the session's cancelled flag after the
transfer wait, after the token grant, and once more under the session lock together with the
save, so a sign-in the user abandoned never persists. The renderer's sign-in store carries an
attempt generation that every continuation checks after each await, so a poll from a closed
attempt cannot publish over the one on screen (and its backend session is cancelled). The ready
screen comes down only after the backend recorded the acknowledgement. A composer still mounted
takes over the notice claim when its owner unmounts. One thin test per hole.
2026-09-11 03:45:32 +05:30

6.9 KiB

apps/desktop/src/ — backend contract, slash palette, Bot Mode

Applies on top of apps/desktop/AGENTS.md (the judgment guide) and the root AGENTS.md. Root TypeScript style rules apply.

The desktop is its own chat surface on a hermes serve backend

Electron + React + nanostores (@assistant-ui/react) talking to a tui_gateway backend over JSON-RPC (requestGateway(method, params)); transport lives in the framework-agnostic apps/shared (@hermes/shared: JsonRpcGatewayClient + WS URL helpers), which the web dashboard also consumes. The desktop has no build/runtime dependency on the dashboard frontend: it spawns a headless hermes serve (headless_backend=True → cmd_dashboard skips _build_web_ui and exports HERMES_SERVE_HEADLESS=1 so mount_spa() disables the SPA even if a stray web_dist/ exists). dashboard and serve share cmd_dashboard/start_server but neither launches the other. It does NOT embed hermes --tui — own composer, transcript, slash pipeline.

One backward-compat fallback: serve is newer, so the spawn (electron/backend-command.ts + backendSupportsServe() in electron/main.ts) checks whether the resolved runtime registers serve and ONLY when it does not (older managed install / PATH hermes not yet updated) rewrites argv to legacy dashboard --no-open. Without it a new app against an un-upgraded runtime crashes on an unknown subcommand and bricks every mid-upgrade user. Keep it narrow and tested.

Lifecycle: serve dies with the app by design; the messaging gateway survives it (spawned detached via /api/gateway/*). Never re-parent the gateway under the backend — gateway/AGENTS.md.

Slash commands: curated client-side, dispatched to the backend

  • The backend already provides everything: commands.catalog and complete.slash include built-ins, user quick_commands, AND skill-derived commands. No new RPC is needed to see skills.
  • src/lib/desktop-slash-commands.ts is the load-bearing file: DESKTOP_COMMAND_SPECS (built-ins and their desktop surfaces) + NO_DESKTOP_SURFACE block-lists (terminal-only / messaging-only / picker-owned / settings-owned / advanced). isDesktopSlashCommand(name) gates execution (true for built-ins AND any non-built-in so typed skill/quick commands run); isDesktopSlashSuggestion(name) gates discovery — used by BOTH completion paths in app/chat/composer/hooks/use-slash-completions.ts and by filterDesktopCommandsCatalog; isDesktopSlashExtensionCommand(name) is true for anything not a known built-in, and both suggestion and catalog paths let extensions through (the allow-list once silently dropped every skill/quick command from completions even though they executed when typed).
  • Dispatch: app/session/hooks/use-prompt-actions/slash.ts (runSlash) — desktop-owned built-ins (/skin, /help, /new, ...) locally or via commands.catalog; everything else slash.exec → command.dispatch fallback; a skill command resolves to {type: "skill", message} and is submitted as a normal prompt.

Rule: palette curation hides noise (terminal-only / messaging-only built-ins), NEVER user-activated extensions. If you tighten desktop-slash-commands.ts, keep isDesktopSlashExtensionCommand flowing into both paths. Test: from apps/desktop, npx vitest run src/lib/desktop-slash-commands.test.ts (workspace deps install at the repo root).

Bot Mode (src/plugins/hermes-bots/) — one bot = ONE canonical forever-chat, identified by NAME

Each bot is a Hermes profile with a persistent identity. This invariant regressed repeatedly, cost users conversation history each time, and is not open for re-litigation in a routine PR.

The chat's only identity is (profile, session titled exactly "Bot Chat"); the state DB's UNIQUE(title) index makes that pair a registry of at most one row. Clicking a bot row:

  1. Resolve the registry, every time: session.list {title, include_hidden: true} (indexed, window-free; hidden rows resolve because canonical chats are always hidden; compression lineages resolve to the live tip). Row exists → open it. That is the whole happy path.
  2. No row → create it, titled Bot Chat, born hidden, kicked off with the bot's intro. Creation adopts-before-minting: it re-runs the lookup first so a concurrent/pre-existing row is opened, never forked (set_session_title silently drops conflicting titles — returns 0 rows — which is how the 2026-08 infinite fork loop started).

There is NO session-id pin. The old design stored a pointer in ui_meta['hermes-bots'].chat; five hardening waves (#88690, #90732, #90751, the #91791 revert, #92042) each guarded a new way it dangled or was stolen (rows[0] steals, last_session adoptions, transient clears, a pin re-anchored onto a cron session). A name cannot dangle; legacy chat keys in ui_meta are ignored and dropped. Recency must never win (#91791 → #92042): canonical Bot Chats are unconditionally hidden from the Sessions sidebar, so the bot row is the ONLY door — "newest visible session wins" walls the whole relationship off behind a row that previews one session and opens another. Side-chats ("New chat with this agent") are not plumbing-titled, stay visible in the sidebar, and are never the row's target.

Reviewer corollaries: no per-bot session browser (removed in #90732; don't add it back). Reject any stored session-id pointer as canonical identity — including "as a fallback tier" or "for verification". Reject anything consulting recency/visibility/"where the user left off" for the row's target; such reports are about side-chats and the fix belongs in the Sessions sidebar hide-sweep. The gateway reports the registry row as canonical_session on profiles.list (resolved server-side by title); roster preview, activity signals, and the /new→/compact guard all read it, so preview identity and click identity are the same row by construction. Contract tests: in src/plugins/hermes-bots/: canonical-chat-registry.test.ts (tripwire: the open path never reads/writes a stored pointer), canonical-chat-creation.test.ts, canonical-chat-adopt-on-conflict.test.ts, bot-row-opens-canonical-chat.test.ts, hide-bot-chats.test.ts; plus repo-root tests/tui_gateway/test_profiles_list_canonical_session.py.

Free tier surfaces (src/store/free-tier*.ts, Billing, statusbar chip, onboarding ready screen)

$freeTierStatus mirrors free_tier.status (pull; refreshed with the status snapshot and after a sign-in). deriveBillingView branches on billing.free_tier BEFORE logged_in (status free_tier: notice + one Sign in, Plan/Model/Connectors summary, no payment or usage rows). The sign-in dialog is a single claimed owner (first mount wins, like the real-profile consent prompt); its states map 1:1 to the poll route's status + reason. Copy is the ruled free-tier copy: never "guest", "anonymous", "claim" or "Nous Portal" in user-facing text.