Desktop application
Hermes Desktop is a native chat client for Hermes Agent. It joins an Electron shell, a React workspace, and one or more Hermes gateways so a user can run agent sessions, complete setup, manage models and preferences, update the app, and use plugin features without a terminal. Packaged builds carry the agent runtime as an immutable payload. Source and development builds use an explicitly selected Hermes checkout. Desktop belongs to the user interfaces area and is separate from the web dashboard and the TUI gateway and RPC surface.
System boundaries
Desktop keeps machine control, user experience, and agent work in separate authorities. The renderer presents live gateway state. It does not own sessions, tools, models, or streamed work.
flowchart LR
User[User] --> Renderer[React workspace]
Renderer -->|typed native requests| Electron[Electron shell]
Renderer -->|REST and WebSocket JSON-RPC| Gateway[Hermes gateway]
Electron -->|ensures or attaches to| Gateway
Gateway --> Agent[Sessions, models, tools, and streams]
Electron shell
The Electron shell owns the app process and the local machine. It manages windows, backend connections, local files, terminals, notifications, previews, updates, and process recovery. It exposes named capabilities through the preload bridge instead of general Node.js access. The single-instance owner also controls launch recovery and backend startup. apps/…/main.ts• L736-774, apps/…/preload.ts• L32-134.
Native content follows a trust path. Content-driven windows are denied. External pages open only through a trusted user action. Gateway file saves use the connection and profile that own the file. apps/…/window-open-policy.ts• L1-58, apps/…/main.ts• L11730-11741, apps/…/gateway-file-download.ts• L104-161.
References: apps/…/main.ts• L736-774 apps/…/preload.ts• L32-134 apps/…/window-open-policy.ts• L1-58 apps/…/gateway-file-download.ts• L104-161
React workspace
The React workspace owns navigation, panes, settings, and interaction state. It turns gateway state into chat, lists, previews, terminals, and setup surfaces. The same renderer can run in native Desktop or as a gateway-served Webapp with fewer host capabilities. apps/…/main.tsx• L1-129, apps/…/host-capabilities.ts• L1-84.
References: apps/…/main.tsx• L1-129 apps/…/host-capabilities.ts• L1-84
Gateway service
The gateway owns durable sessions, model calls, tools, configuration, schedules, and stream events. Desktop attaches to the gateway that owns a profile instead of copying agent work into the renderer. A connection identifies a backend source. A profile identifies an agent context on that source, so a profile name alone is not a complete backend identity. apps/…/local-gateway.ts• L61-87, apps/…/connection-config.ts• L827-930, apps/…/client.ts• L592-635.
Local profiles normally share one host gateway and carry profile scope in requests. Isolated or unscopable mutations use a profile-owned backend. URL and Cloud connections share the remote route. SSH and URL configuration can map a Desktop profile label to a different profile name on the backend. apps/…/connection-config.ts• L434-443, apps/…/connection-config.ts• L576-624, apps/…/desktop-profile.ts• L218-283.
References: apps/…/local-gateway.ts• L61-87 apps/…/connection-config.ts• L434-443 apps/…/connection-config.ts• L576-624 apps/…/connection-config.ts• L827-930 apps/…/client.ts• L592-635
Backend lifecycle
Desktop treats backend access as a lifecycle. It selects a connection and profile, proves that the target is usable, binds the renderer to that target, and can reconnect or move the work without rebuilding the whole window.
Connection and profile routing
A request keeps its (connection, profile) owner when it crosses the renderer, Electron, and gateway boundaries. Session, configuration, capability, plugin, messaging, cron, file, and terminal requests use this owner when several sources expose the same profile name. Main owns remembered connection profiles so a new window can restore the right remote route before a renderer exists. apps/…/desktop-profile.ts• L111-126, apps/…/desktop-profile.ts• L218-283, apps/…/client.ts• L592-697.
Profile names that cross into backend process arguments use the shared profile-id grammar. Invalid values do not become new backend directories. Local skin and boot preferences use the same grammar, so display state and backend state name the same profile. apps/…/profile-id-guard.ts• L1-30, apps/…/desktop-boot-preference.ts• L16-30, apps/…/local-skin.ts• L109-121.
References: apps/…/desktop-profile.ts• L111-126 apps/…/desktop-profile.ts• L218-283 apps/…/profile-id-guard.ts• L1-30 apps/…/desktop-boot-preference.ts• L16-30 apps/…/client.ts• L592-697
Primary startup and local ownership
Primary startup first restores a saved route. When no remote is selected, Desktop ensures a usable local gateway owner and attaches to its endpoint. The owner outlives a window, so closing or switching a window disconnects the viewer rather than stopping shared agent work. apps/…/local-gateway.ts• L15-57, apps/…/local-gateway.ts• L220-256, apps/…/main.ts• L4822-4843.
Local dials use short-lived native grants. The grant is tied to the gateway instance, profile, purpose, and requesting window. Stale control data causes one bounded re-discovery; a failed second attempt becomes a real connection error. apps/…/local-gateway.ts• L274-315, apps/…/local-gateway.ts• L332-380, apps/…/local-gateway.ts• L626-683.
References: apps/…/local-gateway.ts• L15-57 apps/…/local-gateway.ts• L220-256 apps/…/local-gateway.ts• L274-315 apps/…/main.ts• L4822-4843
Remote and SSH connections
Remote mode keeps the gateway host as the execution boundary. Agent tools, terminal commands, and file operations run on that host, not on the computer showing the Desktop window. URL and Cloud gateways use token or OAuth authentication. OAuth connections mint a fresh WebSocket ticket and treat a confirmed 401 or 403 as a sign-in problem; network errors remain connection problems. apps/…/connection-config.ts• L13-19, apps/…/connection-config.ts• L250-306, apps/…/connection-config.ts• L109-197.
SSH mode creates a tunnel to a remote Hermes backend. It checks the remote install and platform, uses bounded operations, rejects changed host keys, and reuses or cleans up a dashboard only when Desktop can prove ownership. A remote backend can serve several profiles through one connection. apps/…/remote-lifecycle.ts• L194-379, apps/…/ssh-connection.ts• L839-943, apps/…/ssh-shared-profile-backend.ts• L1-149.
References: apps/…/connection-config.ts• L13-19 apps/…/connection-config.ts• L109-197 apps/…/connection-config.ts• L250-306 apps/…/remote-lifecycle.ts• L194-379 apps/…/ssh-connection.ts• L839-943 apps/…/ssh-shared-profile-backend.ts• L1-149
Reconnection and rehoming
Boot and reconnect use bounded waits and backoff. A sleep, network change, restart, or stale endpoint can rebuild the socket and reattach live sessions. A connection or profile switch is a soft re-home: the shell stays open while gateway-bound state is cleared and the new route becomes authoritative. Running jobs keep their owner route and may continue to emit events in the background. apps/…/use-gateway-boot.ts• L208-255, apps/…/use-gateway-boot.ts• L432-637, apps/…/README.md• L212-218.
Cross-profile reads use bounded aggregation. A slow or offline source becomes a named error beside healthy rows instead of blocking the whole sidebar or looking like an empty list. apps/…/global-remote-session-route.ts• L31-101, apps/…/profile-session-routing.ts• L1091-1180.
References: apps/…/use-gateway-boot.ts• L208-255 apps/…/use-gateway-boot.ts• L432-637 apps/…/README.md• L212-218 apps/…/global-remote-session-route.ts• L31-101 apps/…/profile-session-routing.ts• L1091-1180
Bundled runtime payload
Bundled builds run the agent from the payload named by the build stamp. Electron does not search PATH, select another Python, or repair a missing payload at runtime. A missing or damaged bundled runtime is an install failure and directs the user to reinstall Desktop. apps/…/payload-backend.ts• L14-48, apps/…/main.ts• L4824-4843, apps/…/main.ts• L5055-5065.
Linux AppImages need a stable payload path because their mount disappears on exit. The first launch copies the payload to a per-build data directory, verifies the copy, and reuses it on later launches. Cleanup keeps copies used by a live Desktop or gateway service. apps/…/appimage-payload.ts• L1-5, apps/…/appimage-payload.ts• L117-139, apps/…/appimage-payload.ts• L430-495, apps/…/cli-provision.ts• L59-138.
References: apps/…/payload-backend.ts• L14-48 apps/…/payload-backend.ts• L78-109 apps/…/appimage-payload.ts• L117-139 apps/…/appimage-payload.ts• L430-495 apps/…/cli-provision.ts• L59-138
Update handoff
Desktop updates the client and its connected backend as separate targets. It waits for a safe boundary, hands work to the owner of the installation or source, and reports the result after the new process or package is ready.
Update ownership
Packaged clients use platform owners: Windows sideload builds use App Installer, Store builds use Microsoft Store, and macOS builds use electron-updater. Linux has no published update feed. Source installs use their checkout update path. Remote and SSH backends update at their own source, while Cloud owns updates for its agent instances. apps/…/BUILDING.md• L3-21, apps/…/BUILDING.md• L315-328, apps/…/system.ts• L148-171.
The payload and package are checked as one release unit during packaging. The pack step proves that the payload arrived without missing files, extra files, changed sizes, or changed link targets before platform relocation and signing. apps/…/packaged-payload.mjs• L37-73, apps/…/after-pack.mjs• L63-84.
References: apps/…/BUILDING.md• L3-21 apps/…/BUILDING.md• L315-328 apps/…/packaged-payload.mjs• L37-73 apps/…/after-pack.mjs• L63-84
Relaunch and result reporting
Before an update, Desktop waits for active backend work to reach a safe boundary. It starts the responsible updater and may exit while the handoff continues. A detached relaunch helper is used when the platform must replace the running package. On Linux AppImage relaunch, the helper starts the image without the old mount paths or inherited high file descriptors. apps/…/app-relaunch.ts• L27-107, apps/…/relaunch-target.ts• L65-79, apps/…/relaunch-target.ts• L137-172.
A run marker and correlation id let the next boot match one result to one update attempt. The handoff is successful only when the updater claims the run. If the claim fails, Desktop keeps running or restores its backend and shows a recoverable error. apps/…/checkout-handoff.test.ts• L150-204, apps/…/checkout-handoff.test.ts• L346-367, apps/…/checkout-handoff.test.ts• L369-433.
References: apps/…/app-relaunch.ts• L27-107 apps/…/relaunch-target.ts• L65-79 apps/…/relaunch-target.ts• L137-172 apps/…/checkout-handoff.test.ts• L150-204 apps/…/checkout-handoff.test.ts• L346-367
Local API integration
Desktop uses gateway APIs for agent work and the native or browser bridge for host capabilities. REST carries durable data and settings. WebSocket JSON-RPC carries interactive turns, prompts, approvals, and live events.
Gateway transport
The transport preserves connection and profile ownership across local, remote, Cloud, multiplexed, and pooled backends. Local WebSockets use one-use native grants. Remote WebSockets use tokens or single-use OAuth tickets. Renderer paths stay relative to the selected HTTP origin. apps/…/client.ts• L14-35, apps/…/backend-api-url.ts• L11-49, apps/…/connection-config.ts• L93-106.
The session contract covers creation, prompts, approvals, edits, branches, compression, workspace changes, and model changes. Session reads and writes retain the owner route. Older gateways have narrow fallbacks for missing endpoints. apps/…/sessions.ts• L115-176, apps/…/sessions.ts• L244-435.
Gateway file saves keep the backend owner with the request. Electron streams a result to a temporary file and moves it to the chosen destination only after the transfer succeeds. apps/…/gateway-file-download.ts• L104-183, apps/…/main.ts• L7373-7442.
References: apps/…/client.ts• L14-35 apps/…/backend-api-url.ts• L11-49 apps/…/connection-config.ts• L93-106 apps/…/sessions.ts• L115-176 apps/…/sessions.ts• L244-435 apps/…/gateway-file-download.ts• L104-183
Browser-hosted transport
The renderer can run from a gateway-served Webapp without Electron. It keeps API and socket traffic on the serving origin and uses browser-safe equivalents for files, uploads, windows, terminal access, plugins, preferences, and notifications. Its startup profile is scoped to the serving page and follows profile rename or deletion. Native process, filesystem, update, and window powers are not recreated in the page. apps/…/browser-desktop-bridge.ts• L25-159, apps/…/browser-startup-profile.ts• L8-75, apps/…/host-capabilities.ts• L19-80.
References: apps/…/browser-desktop-bridge.ts• L25-159 apps/…/browser-startup-profile.ts• L8-75 apps/…/host-capabilities.ts• L19-80
Native capability bridge
The preload bridge exposes named capabilities for windows, files, clipboard, notifications, updates, Quick Entry, HUD, previews, screenshots, and helper overlays. Auxiliary windows use the same session and owner scope as the main window. Device preferences stay local, while gateway configuration stays backend state. apps/…/preload.ts• L32-420, apps/…/ui-preferences.ts• L1-16.
Native file and plugin doors resolve paths in Electron. A remote gateway's reported home belongs to another machine and cannot select this machine's Desktop plugin root or local file door. apps/…/fs-ipc.ts• L120-166.
References: apps/…/preload.ts• L32-420 apps/…/ui-preferences.ts• L1-16 apps/…/fs-ipc.ts• L120-166
Chat and onboarding surfaces
The main workspace turns gateway sessions into live chat. It combines durable transcript state with streaming text, tool activity, approvals, attachments, voice, queues, previews, scheduled work, and focused helper windows. First-run setup uses the same session model, so setup is a guided conversation rather than a separate agent path.
Chat workspace
The chat view connects a selected durable session to a live runtime and renders assistant text, reasoning, tools, subagents, usage, prompts, notices, and errors. Session ownership remains separate from the visible route, so a profile switch or reconnect can preserve the correct backend target. apps/…/index.tsx• L94-126, apps/…/wiring.tsx• L418-522.
The composer is shared by the main chat, session tiles, Quick Entry, HUD, and onboarding. It accepts text, files, links, voice input, directives, context references, and answers to blocking prompts. While a turn runs, the user can send, queue, steer, stop, or answer. Its scope keeps attachments, focus, awaiting-input state, and owner profile separate for each visible composer. apps/…/index.tsx• L134-233, apps/…/index.tsx• L972-1055, apps/…/scope.tsx• L11-80.
The model pill and model catalog are the same selection surface across the composer and other Desktop model pickers. They show the model served by the current session surface, gate speed labels by the model's capabilities, and keep manual new-chat choices visibly pinned. apps/…/model-pill.tsx• L39-80, apps/…/model-catalog-menu.tsx• L239-289, apps/…/model-status-label.ts• L222-274.
References: apps/…/index.tsx• L94-126 apps/…/wiring.tsx• L418-522 apps/…/index.tsx• L134-233 apps/…/index.tsx• L972-1055 apps/…/scope.tsx• L11-80 apps/…/model-pill.tsx• L39-80 apps/…/model-catalog-menu.tsx• L239-289
Stream reconciliation
The stream layer joins WebSocket events with stored history. It keeps tool and reasoning parts with the turn that owns them, preserves late tool events on their original assistant bubble, and avoids duplicate output after reconnect or interim commentary. apps/…/index.ts• L165-251.
Turn completion has two related signals: message.complete and the later session.info report with running=false. Desktop tracks reports owed by completed turns so a late report cannot settle a newer turn. If the completion frame is missing, a confirmed end report can still release the composer and hydrate the stored transcript. apps/…/turn-end-report.ts• L1-65, apps/…/message-stream.ts• L402-501, apps/…/session-info.ts• L319-511.
References: apps/…/index.ts• L165-251 apps/…/turn-end-report.ts• L1-65 apps/…/message-stream.ts• L402-501 apps/…/session-info.ts• L319-511
Transcript windows and session lists
Long transcripts use a bounded render window and fetch older durable pages only when the user asks. Session lists group recents, projects, profiles, pinned chats, messaging rows, and search results while retaining the row's profile and connection owner. Large flat lists use virtualization. Search rows keep the backend title and archived state, so a matched message does not become the session name and its menu uses the correct archive verb. apps/…/transcript-window.ts• L20-185, apps/…/transcript-backfill.ts• L79-213, apps/…/sessions-section.tsx• L273-311, apps/…/virtual-session-list.tsx• L92-193, apps/…/search-result-to-session.test.ts• L1-85.
Session tiles persist across restarts and resume only after their owner gateway is open. A pane can leave the visible layout while its live state remains active. apps/…/pane-mirror.ts• L1-211, apps/…/session-tile.tsx• L168-257.
References: apps/…/transcript-window.ts• L20-185 apps/…/transcript-backfill.ts• L79-213 apps/…/sessions-section.tsx• L273-311 apps/…/virtual-session-list.tsx• L92-193 apps/…/search-result-to-session.test.ts• L1-85
First-run setup
First-run setup is a backend-owned run shown inside Desktop chat. Desktop starts or resumes the run in the selected default context, opens its session, and follows completion, skip, and reconnect state. Provider setup supports browser sign-in, device codes, API keys, custom endpoints, model confirmation, and recovery to another provider. apps/…/onboarding-run.ts• L125-198, apps/…/index.tsx• L1-180, apps/…/flow.tsx• L46-155.
flowchart TD
State[Read backend setup state] -->|setup due| Start[Start or resume setup run]
Start --> Open[Open setup session]
Open --> Guide[Show sign-in and model steps]
Guide -->|complete| Done[Backend ends the run]
Guide -->|skip| Skip[End setup]
Done --> Restore[Restore normal workspace]
Skip --> Restore
References: apps/…/onboarding-run.ts• L125-198 apps/…/index.tsx• L1-180 apps/…/flow.tsx• L46-155
Preview, terminal, and auxiliary surfaces
The preview surface shows local files, generated artifacts, and live web pages beside chat. Native Desktop uses an isolated guest surface. Embedded content receives no app credentials and cannot open an OS page by itself. apps/…/preview-pane.tsx• L124-133, apps/…/inline-preview-directive.tsx• L13-51, apps/…/window-open-policy.ts• L1-58.
The terminal is a persistent PTY surface rather than a disposable view. Hidden tabs keep their shell, scrollback, current directory, and agent reader. The active terminal owns global selection shortcuts and can add selected shell or preview text to the chat composer. apps/…/use-terminal-session.ts• L50-64, apps/…/use-terminal-session.ts• L164-195, apps/…/use-terminal-session.ts• L554-588, apps/…/pty-output.ts• L1-11.
Focused chat surfaces can open in separate native windows. Electron owns their lifetime. The renderer keeps their session, profile, and connection scope aligned with the main chat. apps/…/preload.ts• L104-194, apps/…/controller.tsx• L100-126.
References: apps/…/preview-pane.tsx• L124-133 apps/…/inline-preview-directive.tsx• L13-51 apps/…/use-terminal-session.ts• L50-64 apps/…/use-terminal-session.ts• L554-588 apps/…/preload.ts• L104-194
Settings and preferences
Settings separate gateway-owned agent behavior from device-local Desktop behavior. A settings page can target a selected connection and profile. Appearance, window, shortcut, notification, privacy, and update choices belong to this installation or window.
Gateway connections
The Connections surface manages named local, URL, Cloud, and SSH sources. It supports source tests, sign-in state, primary and launch choices, removal, profile overrides, and update actions. A remote connection test exercises the authenticated HTTP and WebSocket legs that the app will use. apps/…/connections-registry.tsx• L118-196, apps/…/connections-registry.tsx• L332-555, apps/…/main.ts• L15089-15104.
References: apps/…/connections-registry.tsx• L118-196 apps/…/connections-registry.tsx• L332-555 apps/…/main.ts• L15089-15104
Profile-scoped configuration
Configuration pages read and write the gateway schema for the selected target. Desktop keeps local drafts and caches separate by connection and profile. The scope covers models, delegation, tools, connectors, MCP, web access, billing, memory, and voice. A model picked in a live chat affects that session or its next turn; Settings changes the profile default for new sessions. apps/…/config-settings.tsx• L70-289, apps/…/use-model-controls.ts• L100-131, apps/…/use-model-controls.ts• L238-256.
References: apps/…/config-settings.tsx• L70-289 apps/…/use-model-controls.ts• L100-131 apps/…/use-model-controls.ts• L238-256
Device preferences and maintenance
Device-local settings control theme, layout, text scale, keep-awake, notifications, shortcuts, clipboard behavior, and local Webapp access. They do not become gateway agent state. The Command Center exposes maintenance actions such as doctor, security audit, backup, memory status, and debug share. apps/…/ui-preferences.ts• L1-16, apps/…/context.tsx• L41-146, apps/…/maintenance.tsx• L52-170.
References: apps/…/ui-preferences.ts• L1-16 apps/…/context.tsx• L41-146 apps/…/maintenance.tsx• L52-170
Backup and agent transfer
Backup creates an archive for a selected gateway. Transfer moves a local agent into a Hermes Cloud agent while preserving the Cloud host's sign-in, model, and Cloud services. The target creates an undo archive before restore, so a failed or partial restore has a recovery point. apps/…/backup-settings.tsx• L63-243, apps/…/agent-transfer.ts• L249-430.
flowchart LR
Source[Selected local agent] --> Backup[Create source backup]
Backup --> Upload[Stream archive to Cloud agent]
Upload --> Restore[Restore while keeping Cloud host settings]
Restore --> Ready[Open transferred agent]
Restore --> Undo[Offer undo from target backup]
References: apps/…/backup-settings.tsx• L63-243 apps/…/agent-transfer.ts• L249-430
Session retention
The Sessions settings surface restores archived conversations, permanently deletes them, and controls optional automatic archiving. The retention rule remains gateway-owned, so Desktop and other Hermes surfaces use the same policy. apps/…/sessions-settings.tsx• L53-144, apps/…/sessions-settings.tsx• L224-229.
References: apps/…/sessions-settings.tsx• L53-144 apps/…/sessions-settings.tsx• L224-229
Plugin-facing UI
Desktop lets agent and Desktop plugins add focused product surfaces without taking ownership of the app shell. The host owns navigation, scope, native actions, settings placement, package review, and cleanup. Plugins contribute features inside those boundaries.
Capability catalog and package management
The Capabilities page brings Skills, Plugins, Connectors, and Toolsets into one connection- and profile-aware surface. Users can inspect a package source, choose its target, install or enable it, update it, reveal local files, and remove the part that applies to the current machine or backend. Remote agent backends cannot materialize a Desktop half on this machine. apps/…/index.tsx• L32-101, apps/…/plugins-tab.tsx• L96-131, apps/…/plugins-tab.tsx• L447-520.
The public catalog uses published snapshots rather than per-entry requests. Desktop validates catalog links, merges installed and available entries, and prefetches a catalog only while the browser is idle. A failed catalog stays available for an explicit retry instead of causing repeated background work. apps/…/catalog-data.ts• L54-75, apps/…/catalog-data.ts• L211-301, apps/…/catalog-data.ts• L304-330.
References: apps/…/index.tsx• L32-101 apps/…/plugins-tab.tsx• L96-131 apps/…/catalog-data.ts• L54-75 apps/…/catalog-data.ts• L211-330
Contribution registry
The contribution registry places plugin panes, routes, sidebar items, commands, settings pages, titlebar items, status items, context-menu rows, completion sources, and composer slots into host-owned areas. Runtime plugins can load, reload, enable, and disable without taking down the shell. The host tracks plugin-owned listeners and other cleanup work. apps/…/registry.ts• L5-27, apps/…/runtime-loader.ts• L364-382, apps/…/runtime-loader.ts• L463-524.
The plugin context is a trust boundary, not a security sandbox. It provides scoped gateway access, storage, translations, notifications, links, dialogs, clipboard, and app actions. The SDK exposes those doors as one authoring surface and gives plugins read-only views of focused session state. apps/…/plugin.ts• L111-179, apps/…/index.ts• L1-19, apps/…/index.ts• L161-223.
References: apps/…/registry.ts• L5-27 apps/…/runtime-loader.ts• L364-382 apps/…/runtime-loader.ts• L463-524 apps/…/plugin.ts• L111-179 apps/…/index.ts• L1-19
Plugin settings and session controls
Settings exposes plugin pages through the same profile selector used by gateway configuration. Agent plugins with a schema receive a generated form whose draft and write remain bound to one profile. Plugin session controls use the host's pin, order, and color stores and resolve a durable or live id to the loaded session row before writing. apps/…/plugin-settings.tsx• L90-207, apps/…/plugin-settings.tsx• L336-445, apps/…/sessions.ts• L11-80.
References: apps/…/plugin-settings.tsx• L90-207 apps/…/plugin-settings.tsx• L336-445 apps/…/sessions.ts• L11-80
Hermes Bots surfaces
The Hermes Bots plugin presents one row per agent profile and opens that bot's canonical Bot Chat. It adds a Bots pane, profile editing, routines, group chats, cross-connection mentions, screen access, and bot-to-bot relay. Bot Chats stay hidden from the normal Sessions list so the roster row remains the one door to the continuous conversation. apps/…/plugin.tsx• L1-16, apps/…/plugin.tsx• L433-490.
Above a Bot Chat composer, the plugin can show unsettled teammate deliveries. The strip reads delivery receipts, reports queued, working, waiting, failed, or unknown outcomes, opens the target bot's own chat, and never resends an uncertain delivery. This keeps the UI honest when a gateway or connection fails between send and receipt. apps/…/teammate-waits.tsx• L1-11, apps/…/teammate-waits.tsx• L118-131, apps/…/teammate-waits.tsx• L212-258, apps/…/plugin.tsx• L439-443.
References: apps/…/plugin.tsx• L1-16 apps/…/plugin.tsx• L433-490 apps/…/teammate-waits.tsx• L1-11 apps/…/teammate-waits.tsx• L118-131 apps/…/teammate-waits.tsx• L212-258
Change checklist
When these files or sections are changed, remember to consider these:
- Backend route changes must preserve the full
(connection, profile)owner through session, settings, plugin, messaging, cron, file, terminal, preview, audio, and background requests. - Local shared-host changes must keep profile query scope aligned with the route table. Mutations that the server cannot scope must not fall through to the primary profile.
- Profile-id changes must update the shared grammar used by Desktop routes, boot preferences, local skins, remote mappings, plugin-created profiles, and backend argv.
- Local gateway changes must keep endpoint validation, one-use grants, stale-owner recovery, and profile-specific ticket minting aligned.
- Remote connection changes must keep URL normalization, OAuth ticket refresh, access-proxy header filtering, SSH profile mapping, and connection preflight consistent.
- Payload changes must keep the build stamp, prepared payload, packaged payload, relocation step, runtime paths, AppImage stable copy, CLI links, and update strategy consistent.
- Update changes must preserve platform ownership, backend drain order, detached relaunch behavior, handoff claim, correlation, and recovery when the updater does not start.
- API bridge changes must update the Electron handler, preload bridge, renderer type, browser equivalent where needed, and every auxiliary window that uses the capability.
- Composer changes must keep per-surface owner scope, IME input, queue state, blocking prompts, voice interruption, model capability labels, and explicit stop behavior aligned.
- Stream changes must preserve message identity, late turn-end report ownership, runtime rebind rules, missing-completion recovery, and transcript hydration scope.
- Sidebar changes must preserve profile and connection provenance, archived-row verbs, search titles, pinned rows, project grouping, and virtualized row identity.
- Plugin changes must keep contribution cleanup, scoped gateway requests, reviewed catalog sources, profile-bound settings, canonical Bot Chat identity, and no-resend teammate reporting aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A request carries only a profile name | Work can go to an equal profile on another gateway | Carry the owning connection and profile at the request boundary |
An invalid profile value reaches --profile | Desktop can create or target a phantom backend directory | Validate through the shared profile-id grammar |
| A stale local gateway descriptor is reused | Reconnect loops against a dead owner or returns repeated ticket errors | Forget the descriptor once and re-run the canonical ensure |
| OAuth ticket minting treats a network error as sign-out | A temporary outage forces needless reauthentication | Retry transient transport failures but fail immediately on confirmed 401 or 403 |
| A remote header reaches a different origin or overrides transport headers | Credentials can leak or the request can be malformed | Match the gateway origin and reject protected header names |
| A bundled payload is missing or altered | Desktop can run an unintended runtime or ship a broken package | Use the stamped payload only and compare the prepared and packaged trees |
| An AppImage runs its payload only from the mount | The gateway, CLI links, or update flow break after the app exits | Copy and verify one stable payload directory per build |
A late running=false report settles the next turn | The newer turn stops early or loses its prompt state | Track one owed end report per completed turn |
| A missing completion frame leaves the session busy | The composer queues every later input and never sends it | Use an authoritative end report to settle and hydrate the affected session |
| A model pill reads primary global state in a tile | A tile shows or sends the wrong model choice | Read the tile's SessionView and owner-scoped model options |
| A search hit drops its archived flag or title | The row shows message text and offers the wrong archive action | Map backend title and archive state onto the synthesized row |
| A plugin teammate delivery has an unknown result and is resent | An agent may act twice | Show the unknown outcome and require the user to open the target chat |
| An update child starts without claiming the handoff | Desktop exits into an update that did not begin | Require the claim and keep the app alive on claim failure |
Key files
| File | Why to read it |
|---|---|
| apps/…/main.ts | Electron composition root for startup, connections, windows, backend lifecycle, native actions, and updates. |
| apps/…/local-gateway.ts | Local gateway ensure, endpoint validation, profile routing, one-use grants, and stale-owner recovery. |
| apps/…/connection-config.ts | Remote, Cloud, SSH, OAuth, header, and shared-host routing rules. |
| apps/…/desktop-profile.ts | Remembered connection/profile routes and missing-profile cleanup. |
| apps/…/payload-backend.ts | The stamped bundled-runtime contract consumed by Electron. |
| apps/…/appimage-payload.ts | Stable AppImage payload copies and cleanup ownership. |
| apps/…/relaunch-target.ts | Safe detached relaunch targets and mount-free environments. |
| apps/…/after-pack.mjs | Packaged payload checks, relocation, and platform post-pack work. |
| apps/…/packaged-payload.mjs | Exact prepared-to-packaged payload comparison. |
| apps/…/BUILDING.md | Artifact variants, update owners, payload contract, and native release boundaries. |
| apps/…/wiring.tsx | The renderer controller that joins gateway boot, session lists, chat, composer, terminal, and overlays. |
| apps/…/index.tsx | Shared send, queue, steer, stop, voice, attachment, and onboarding composer behavior. |
| apps/…/scope.tsx | Per-composer session, owner, attachment, and focus scope. |
| apps/…/model-catalog-menu.tsx | Shared model selection, capability, speed, pricing, favorite, and custom-model surface. |
| apps/…/sessions-section.tsx | Session grouping, project views, archive verbs, ordering, and row ownership. |
| apps/…/virtual-session-list.tsx | Virtualized rendering and stable profile/session row identity. |
| apps/…/index.ts | Stream assembly and event-to-session-state reconciliation. |
| apps/…/turn-end-report.ts | Late end-of-turn report ownership. |
| apps/…/session-info.ts | Runtime rebind, turn settle, workspace ownership, and recovery behavior. |
| apps/…/use-terminal-session.ts | Persistent PTY, scrollback, resize, selection, theme, and agent-reader behavior. |
| apps/…/flow.tsx | Provider sign-in, model confirmation, and setup recovery surfaces. |
| apps/…/catalog-data.ts | Public catalog parsing, link policy, caching, and idle prefetch. |
| apps/…/registry.ts | Host contribution areas and plugin lifecycle cleanup. |
| apps/…/index.ts | Plugin SDK state views, actions, owner routing, and session doors. |
| apps/…/plugin.tsx | Bot roster, canonical chats, panes, mentions, relay, and plugin wiring. |
| apps/…/teammate-waits.tsx | Read-only teammate delivery status above canonical Bot Chats. |