better-dsh 0.2.5-c → 0.2.5-d

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/desktop-plugin-sdk.md

@@ -1,952 +0,0 @@
----
-sidebar_label: "Desktop Plugin SDK"
-title: "Desktop Plugin SDK (@hermes/plugin-sdk)"
-description: "Extend the native Hermes Desktop app — panes, pages, sidebar nav, status bar, palette commands, keybinds, themes, and a scoped backend namespace, with one import and no build step."
----
-
-# Desktop Plugin SDK
-
-The native [Hermes Desktop](/user-guide/desktop) app is contribution-driven: every
-surface in the window — panes, routes, sidebar nav, status-bar items, palette
-entries, keybinds, themes — registers into one central registry. Core registers
-its surfaces exactly the way a plugin does, so the plugin story is the real one,
-not a bolted-on afterthought.
-
-A **desktop plugin** is a single ESM file that default-exports a `HermesPlugin`.
-It imports one module — `@hermes/plugin-sdk` — and gets everything: the app's
-live state, the gateway JSON-RPC door, a scoped REST/socket backend namespace,
-React Query, and the app's own UI kit so plugin UI looks native by default. No
-repo clone, no `npm run build`, no patching app source. Drop the file in
-`$HERMES_HOME/desktop-plugins/<id>/plugin.js` and the app loads it within seconds
-and hot-reloads every save.
-
-:::warning This is not the web-dashboard plugin SDK
-"Plugin" means several unrelated things across Hermes. This page is the **native
-desktop app** (`hermes desktop`) SDK — the `@hermes/plugin-sdk` module and
-`$HERMES_HOME/desktop-plugins/`. The **web dashboard** (`hermes dashboard`) has
-its own, unrelated plugin system on `window.__HERMES_PLUGIN_SDK__` with a
-`manifest.json` — documented at
-[Extending the Dashboard](/user-guide/features/extending-the-dashboard). Python
-CLI/gateway plugins are documented at [Build a Hermes Plugin](/developer-guide/plugins).
-The three do not share code, APIs, or delivery. Only the backend `plugin_api.py`
-namespace (`/api/plugins/<id>`) is shared between the desktop and dashboard SDKs.
-:::
-
-## Mental model
-
-The SDK follows the VS Code module model. A plugin author imports exactly one
-module and never touches app internals (they are lint-fenced out of a bundled
-plugin, and fail to resolve in a disk plugin). Capability comes in tiers:
-
-- **`host.state.*`** — readonly views over the app's live state (nanostore
-  atoms): active session, per-session turn-busy, cwd, gateway socket status,
-  model, profile, viewport. `gateway` is the WebSocket, not turn-busy.
-- **`host.*` actions** — curated safe verbs: toast, navigate, tail logs,
-  restart the gateway, subscribe to the gateway event stream.
-- **`host.request`** — the gateway JSON-RPC door: sessions, config, skills,
-  cron — everything the app itself calls.
-- **`ctx.rest` / `ctx.socket`** — your plugin's own backend namespace
-  (`/api/plugins/<id>`) if you ship a `plugin_api.py`.
-- **`ui.*`** — the design language: the app's real components, theme variables,
-  icons, and formatters, so your UI matches the app pixel-for-pixel.
-
-## Two delivery modes
-
-| Mode | Where | Who | Build step |
-|------|-------|-----|------------|
-| **Disk** (recommended) | `$HERMES_HOME/desktop-plugins/<id>/plugin.js` | users, agents | none — plain ESM, loaded uncompiled |
-| **Unified package** | `$HERMES_HOME/plugins/<id>/desktop/plugin.js` | plugins that also ship agent-side code | none — same disk pipeline |
-| **Bundled** | `apps/desktop/src/plugins/<id>/plugin.tsx` | in-tree, shipped with the app | the app's own Vite build |
-
-All three take the same `HermesPlugin` contract, appear in **Capabilities → Plugins**,
-and enable/disable live. A unified package is just the disk door scanning inside
-your agent plugin's folder — see
-[One package, both SDKs](#one-package-both-sdks). Everything on this page is
-written against the disk door (what you and the agent write);
-[Bundled plugins](#bundled-plugins) notes the two
-differences. Radio ships as a bundled SDK-only plugin, off by default. Enable it
-in **Capabilities → Plugins** for free live streams, station search, and status-bar
-playback controls with an audio-reactive waveform. It uses the existing plugin
-toggle and contributes nothing while disabled. Reference demos live in the companion
-[`hermes-example-plugins`](https://github.com/NousResearch/hermes-example-plugins)
-repo.
-
-## Quick start — your first plugin
-
-Create `$HERMES_HOME/desktop-plugins/hello/plugin.js` (that's `~/.hermes/...`
-by default). Desktop plugins are app-level — one root for every profile, gateway,
-or remote machine the window connects to. The folder name must equal the plugin `id`.
-
-```javascript
-// ~/.hermes/desktop-plugins/hello/plugin.js
-import { host, haptic, useValue } from '@hermes/plugin-sdk'
-import { jsx, jsxs } from 'react/jsx-runtime'
-
-function HelloPane() {
-  const gateway = useValue(host.state.gateway)
-
-  return jsxs('div', {
-    className: 'flex h-full flex-col gap-2 p-3 text-sm',
-    children: [
-      jsx('div', { className: 'font-medium', children: 'Hello, Hermes' }),
-      jsx('div', {
-        className: 'text-(--ui-text-tertiary)',
-        children: `gateway: ${gateway}`
-      })
-    ]
-  })
-}
-
-export default {
-  id: 'hello', // must match the folder name
-  name: 'Hello',
-  register(ctx) {
-    ctx.register({
-      id: 'pane',
-      area: 'panes',
-      title: 'hello',
-      data: { placement: 'right', width: '260px' },
-      render: () => jsx(HelloPane, {})
-    })
-    ctx.register({
-      id: 'chip',
-      area: 'statusBar.right',
-      order: 130,
-      render: () =>
-        jsx('button', {
-          type: 'button',
-          className: 'px-1.5 text-[0.6875rem] text-(--ui-text-tertiary)',
-          onClick: () => {
-            haptic('tap')
-            host.notify({ kind: 'info', message: 'Hello from my plugin!' })
-          },
-          children: 'hello'
-        })
-    })
-  }
-}
-```
-
-Save it. The app watches `desktop-plugins/`, loads the file within a few seconds,
-and hot-reloads every later save in place. If it doesn't appear, run ⌘K →
-**Reload desktop plugins**. If loading fails, a toast names the error — fix and
-save again.
-
-:::note No JSX, no build
-The disk file is loaded **uncompiled**, so JSX syntax will not parse. Write UI
-with `jsx()` / `jsxs()` calls from `react/jsx-runtime` (or `React.createElement`).
-The only importable specifiers are `@hermes/plugin-sdk`, `react`, and
-`react/jsx-runtime` — everything else fails to resolve, on purpose.
-:::
-
-## The plugin contract
-
-A plugin default-exports a `HermesPlugin`:
-
-```ts
-interface HermesPlugin {
-  /** Stable slug — becomes the `plugin:<id>` source and the id namespace. */
-  id: string
-  /** Human name for Settings / about UI. Defaults to `id`. */
-  name?: string
-  /** Registers on load when the user hasn't chosen (default true). Set false
-   *  for opt-in plugins: they inventory in Capabilities ▸ Plugins, off until the
-   *  user flips the switch. */
-  defaultEnabled?: boolean
-  /** Called once at load; wire contributions through `ctx`. */
-  register: (ctx: PluginContext) => void
-}
-```
-
-`register` receives a **scoped** `PluginContext`. It never touches the registry
-directly — the context auto-tags provenance (`source: 'plugin:<id>'`) and
-namespaces every contribution id (`<id>:<localId>`), so two plugins can never
-collide.
-
-```ts
-interface PluginContext {
-  /** Resolved source tag, e.g. `'plugin:hello'`. */
-  readonly source: string
-  /** Register one contribution (id namespaced, source stamped). Returns a disposer. */
-  register: (c: PluginContribution) => () => void
-  /** Register several at once; the returned disposer removes all of them. */
-  registerMany: (cs: PluginContribution[]) => () => void
-  /** REST to this plugin's own backend namespace (`/api/plugins/<id>`). */
-  rest: <T>(path: string, opts?: PluginRestOptions) => Promise<T>
-  /** Live WebSocket to this plugin's own namespace. Returns a disposer. */
-  socket: (path: string, onMessage: (data: unknown) => void) => () => void
-  /** The curated OS door: native notification, open-external, reveal-in-file-manager, clipboard. */
-  os: PluginOs
-  /** Plugin-scoped JSON persistence (keys live under `hermes.plugin.<id>.`). */
-  storage: PluginStorage
-}
-```
-
-A **contribution** is the one primitive every surface shares:
-
-```ts
-interface Contribution {
-  id: string          // you write the local id; the host namespaces it
-  area: string        // WHERE it goes (a contribution-area constant)
-  title?: string
-  order?: number      // sort within the area (lower = earlier)
-  when?: () => boolean // dynamic visibility; re-evaluated by the area
-  enabled?: boolean
-  render?: () => ReactNode  // the component to mount
-  data?: unknown      // area-specific payload (see the cookbook)
-}
-```
-
-You provide `render`, `data`, or both, depending on the area.
-
-## Contribution areas — the cookbook
-
-Import the area constants from the SDK; each area has its own `data` payload.
-
-| Surface | `area` | You provide |
-|---------|--------|-------------|
-| Layout pane | `PANES_AREA` (`'panes'`) | `title` + `render` + `data: { placement, dock?, width?, height? }` |
-| Full page | `ROUTES_AREA` | `data: { path }` + `render` |
-| Sidebar nav | `SIDEBAR_NAV_AREA` | `data: { path, label, codicon }` |
-| Status bar | `STATUSBAR_AREAS.left` / `.right` | `render` (or `data` as `StatusbarItem`) |
-| Title bar | `TITLEBAR_AREAS.left` / `.center` / `.right` | `data` as `TitlebarTool`, or a mount-scoped `<Contribute>` |
-| ⌘K palette | `PALETTE_AREA` | `data: PaletteContribution` |
-| Keybind | `KEYBINDS_AREA` | `data: KeybindContribution` |
-| Theme | `THEMES_AREA` | `data` as a `DesktopTheme` |
-| Composer | `COMPOSER_AREAS.*` | render slots, or middleware / attachment providers |
-
-### Panes
-
-A pane is a tile in the layout tree. `placement` is the semantic role — the pane
-stacks (as tabs) with existing panes of that role; the user can drag it anywhere
-afterward.
-
-```javascript
-ctx.register({
-  id: 'pane',
-  area: 'panes',
-  title: 'my pane',
-  data: { placement: 'right', width: '260px' },
-  render: () => jsx(MyPane, {})
-})
-```
-
-`placement` is `'main' | 'left' | 'right' | 'top' | 'bottom'`. To land on a
-specific **edge** instead of stacking, add a `dock` gesture — the same thing as
-dragging onto a pane's drop chip:
-
-```javascript
-// Below the conversation, 200px tall.
-data: {
-  placement: 'bottom',
-  dock: { pane: 'workspace', pos: 'bottom' },
-  height: '200px'
-}
-```
-
-`dock.pane` is any pane id (`workspace` is the main thread; also `sessions`,
-`terminal`, `files`, `review`, `logs`); `dock.pos` is
-`'top' | 'bottom' | 'left' | 'right' | 'center'`. Declare a `width`/`height` so
-the pane doesn't claim half the zone.
-
-Closing the only pane contributed by a plugin disables that plugin, which can
-be re-enabled from **Capabilities → Plugins**. When a plugin contributes multiple
-panes, closing one dismisses only that pane and leaves the plugin's other panes,
-commands, and middleware active. **Reset layout** restores dismissed contributed
-panes.
-
-### Pages and sidebar nav
-
-A route mounts a full page in the workspace pane, like any built-in view. Pair it
-with a sidebar nav row (and/or a palette command) to make it reachable.
-
-```javascript
-import { ROUTES_AREA, SIDEBAR_NAV_AREA } from '@hermes/plugin-sdk'
-
-ctx.registerMany([
-  {
-    id: 'page',
-    area: ROUTES_AREA,
-    data: { path: '/my-page' },
-    render: () => jsx(MyPage, {})
-  },
-  {
-    id: 'nav',
-    area: SIDEBAR_NAV_AREA,
-    data: { path: '/my-page', label: 'My Page', codicon: 'project' }
-  }
-])
-```
-
-`codicon` is a [VS Code codicon](https://microsoft.github.io/vscode-codicons/dist/codicon.html)
-id. Navigate to a route from anywhere with `host.navigate('/my-page')`.
-
-### Status bar and title bar
-
-Status-bar items render into the left or right cluster of the bottom bar.
-Simplest is a `render` function; for a plain button use `data` as a
-`StatusbarItem` (`{ id, label?, icon?, detail?, variant?, menuItems?, … }`).
-
-```javascript
-import { STATUSBAR_AREAS, TITLEBAR_AREAS } from '@hermes/plugin-sdk'
-
-ctx.register({
-  id: 'count',
-  area: STATUSBAR_AREAS.right,
-  order: 120,
-  render: () => jsx(MyStatus, {})
-})
-```
-
-Title-bar tools live in `TITLEBAR_AREAS.left | .center | .right` as `TitlebarTool`
-data (`{ id, label, icon, active?, onSelect? }`).
-
-### Palette commands and keybinds
-
-```javascript
-import { PALETTE_AREA, KEYBINDS_AREA } from '@hermes/plugin-sdk'
-
-ctx.registerMany([
-  {
-    id: 'open',
-    area: PALETTE_AREA,
-    data: {
-      id: 'my-page.open',
-      label: 'Open My Page',
-      keywords: ['my', 'page'],
-      run: () => host.navigate('/my-page')
-    }
-  },
-  {
-    id: 'refresh',
-    area: KEYBINDS_AREA,
-    data: {
-      id: 'my-page.refresh',
-      label: 'Refresh My Page',
-      category: 'My Plugin',
-      defaults: ['mod+shift+r'],
-      run: () => void doRefresh()
-    }
-  }
-])
-```
-
-Keybinds are user-rebindable in settings; `defaults` is just the initial binding.
-
-### Themes
-
-A theme contribution ships a full `DesktopTheme` as its `data` (name, label,
-colors, …). It appears in the theme picker like a built-in.
-
-```javascript
-import { THEMES_AREA } from '@hermes/plugin-sdk'
-
-ctx.register({ id: 'noir', area: THEMES_AREA, data: myDesktopTheme })
-```
-
-Registering a theme lists it; it does not select it. `useTheme()` reads the
-painted appearance (`theme`, `themeName`, `availableThemes`, `resolvedMode`) and
-changes it (`setTheme`, `setMode`, `previewTheme`) from a component:
-
-```javascript
-import { Button, useTheme } from '@hermes/plugin-sdk'
-
-function ThemePicker() {
-  const { availableThemes, setTheme, themeName } = useTheme()
-
-  return availableThemes.map(t => (
-    <Button key={t.name} disabled={t.name === themeName} onClick={() => setTheme(t.name)}>
-      {t.label}
-    </Button>
-  ))
-}
-```
-
-A switch driven by something other than a render — a gateway connecting, a
-socket event, any `host.onEvent` callback — has no component to hang the hook
-on. Use `requestTheme(name)` there. An unresolvable name is refused rather than
-coerced to the default skin, so the return value doubles as the availability
-check and a wrong name can never silently reset someone's appearance:
-
-```javascript
-import { host, requestTheme } from '@hermes/plugin-sdk'
-
-host.onEvent('gateway.ready', () => {
-  if (!requestTheme('noir')) {
-    host.notifyError('Connected, but the noir theme is not installed.')
-  }
-})
-```
-
-Both doors persist per profile, so a plugin-driven switch sticks exactly like a
-manual pick. To tint the *active* theme rather than replace it, use
-`setAccentOverride(hex)` and clear it in `ctx.onDispose` — the standalone
-[Accent Picker](https://github.com/NousResearch/hermes-desktop-accent-picker)
-plugin is the worked example (it is also a complete, installable disk plugin).
-
-### Composer extensions
-
-`COMPOSER_AREAS` (`top`, `bottom`, `leading`, `actions`, `attachments`,
-`middleware`) let a plugin add controls around the message composer, provide an
-attachment source, or transform a draft before it is sent (`ComposerMiddleware`
-with a `handler(draft) => draft | null`).
-
-### Transcript directives — inline components the model addresses
-
-`TRANSCRIPT_DIRECTIVE_AREA` makes the transcript itself a contribution area.
-Register a named directive and the agent can render your component inline in
-an assistant message by emitting a paragraph of the form `::name{key="value"}`:
-
-```javascript
-import { TRANSCRIPT_DIRECTIVE_AREA } from '@hermes/plugin-sdk'
-
-ctx.register({
-  id: 'task-card',
-  area: TRANSCRIPT_DIRECTIVE_AREA,
-  data: {
-    name: 'task', // the model writes ::task{id="BB-12"}
-    render: ({ attrs, streaming }) => jsx(TaskCard, { taskId: attrs.id, streaming })
-  }
-})
-```
-
-Rules the host enforces so the surface stays safe:
-
-- The directive must be the **entire paragraph** — `::name` mid-prose stays
-  prose, so plugin components can never hijack running text.
-- Attributes are **untrusted model output** (`key="value"` pairs, string-only).
-  Validate your own fields; render nothing on garbage rather than guessing.
-- An **unclaimed** directive (no plugin registered for the name) renders as
-  the plain paragraph it always was — nothing breaks when a plugin is off.
-- Renders are wrapped in the contribution error boundary: a throw degrades to
-  an inline error chip, never a dead message.
-- First registration wins on a name collision; namespace adventurous names
-  with your slug (`myplugin-board`, not `board`).
-
-Core ships one directive as the reference consumer: `::preview{file="…"}`
-renders the workspace HTML file **live inside the message** — a sandboxed
-`srcdoc` iframe with an opaque origin (scripts run and the widget is fully
-interactive; no reach into the app, its storage, or the bridge). The frame
-sizes itself to the content (height live, width adopted from the content's
-intrinsic span, flush left in the message flow), and a theme prelude hands
-the document the app's resolved tokens (`--foreground`, `--muted-foreground`,
-`--accent`, `--border`, `--card`), the app font, and a transparent
-background — so widget-shaped HTML reads as native while a full page keeps
-its own design. Non-HTML targets and remote gateways fall back to the
-classic preview card. Tell the agent about your directive in a skill (that's
-how it learns to emit it).
-
-Previewed widgets can also **talk back**. Inside the frame,
-`window.hermes.send('get-price eth')` (or a declarative
-`<button data-hermes-send="get-price eth">` — no script needed) hands that
-prompt to the agent as a user turn, off-screen: no bubble takes up the
-transcript, the widget updating is the visible response. The turn is still
-real — it wakes the agent, rides the composer's steer/queue rules, and
-persists (typed `hidden`) so resume and the session DB keep the full record.
-Prompts are trimmed, capped at 500 chars, and throttled to one per second
-per frame.
-
-### Mount-scoped chrome (`Contribute`)
-
-`ctx.register` is for **permanent** contributions. When chrome should live and
-die with a component that's already on screen (a page's own title-bar control
-leaves when the page unmounts), render `<Contribute>` inside it instead:
-
-```javascript
-import { Contribute, TITLEBAR_AREAS } from '@hermes/plugin-sdk'
-
-jsx(Contribute, {
-  area: TITLEBAR_AREAS.center,
-  id: 'my-page:switcher', // namespace with your slug
-  children: jsx(MySwitcher, {})
-})
-```
-
-It registers on mount and disposes on unmount automatically.
-
-## Host API
-
-Everything on `host` is reachable from anywhere in a plugin. State atoms are
-readonly — read with `.get()` in handlers, subscribe with `useValue(atom)` in
-components.
-
-```ts
-host.state.activeSessionId  // ReadableAtom<string | null>
-host.state.awaitingResponse // ReadableAtom<boolean>  true until the first assistant payload
-host.state.busy             // ReadableAtom<boolean>  focused chat is working after a send
-host.state.busyBySession    // ReadableAtom<Record<string, boolean>>  runtime id → mid-turn
-host.state.focusedSessionId // ReadableAtom<string | null>  (runtime id of the FOCUSED session — tile-aware; prefer for session.* RPC)
-host.state.focusedSessionProfile // ReadableAtom<string>  (owner profile of the focused chat — prefer over `profile` for per-bot/profile readouts)
-host.state.focusedStoredSessionId // ReadableAtom<string | null>  (durable id — navigation / session-list matching)
-host.state.focusedUsage     // ReadableAtom<UsageStats | null>  (live streamed usage of the focused session, no RPC needed)
-host.state.cwd              // ReadableAtom<string>
-host.state.gateway          // ReadableAtom<string>  socket state ('idle' | 'connecting' | 'open' | …)
-host.state.model            // ReadableAtom<string>
-host.state.profile          // ReadableAtom<string>
-host.state.viewport         // ReadableAtom<{ width, height, narrow }>
-```
-
-`host.state.gateway` is the WebSocket connection, not whether a chat turn is
-running. A session can be mid-turn while the socket is `open`; another session
-can be idle at the same time. Disable composer or plugin actions from the
-**focused session's** turn-busy (`host.state.busyBySession[sessionId]`, or that
-session's `view.$busy`) — never from `gateway`, and never from a process-global
-busy flag.
-
-```ts
-host.notify({ kind, message, title?, detail?, action? })  // toast; returns id
-host.notifyError(error, fallbackMessage)                   // toast an error
-ctx.os.notify({ title, body?, silent?, icon?, activate?, onActivate?, actions? })
-                                           // native OS notification (attributed to your plugin)
-ctx.os.openExternal(url)                   // OS default handler (browser, mail, spotify:) → Promise<boolean>
-ctx.os.revealPath(path)                    // reveal in Finder / Explorer → Promise<boolean>
-ctx.os.writeClipboard(text)                // system clipboard → Promise<boolean>
-host.navigate('/route')                    // hash-route navigation
-host.openSession(id, { profile?, intent? }) // open a stored session core-style;
-                                           //   profile: soft-swap to that profile's backend first
-                                           //   intent: 'in-place' (default) | 'stack' | 'tab' | 'window'
-host.newChat(profile?)                     // fresh chat draft, optionally in another profile
-host.openWorkspace(id, { render, title?, minWidth?, onClose? })
-                                           // dock a plugin-rendered tab into the MAIN
-                                           //   workspace zone and reveal it; returns a disposer
-host.paneVisibility(paneId)                // ReadableAtom<boolean> — is a contributed pane
-                                           //   actually on screen (its zone's active tab)?
-host.onEvent(type, fn)                     // gateway event stream ('*' = all); returns disposer
-host.logs(...)                             // tail an app log file
-host.status()                              // one-shot system status snapshot
-host.restartGateway()                      // restart the backend gateway
-host.profileRoutes()                       // [{ profile, targetProfile, connectionId, mode }]
-host.requestProfile<T>(route, method, params?)   // registry-routed RPC; no foreground swap
-host.requestProfile<T>(profile, method, params?) // legacy v1/local overload
-host.request<T>(method, params?)           // active-gateway JSON-RPC — the real power
-```
-
-`host.request` is the same JSON-RPC the app itself uses (sessions, config, skills,
-cron, kanban, …). `host.requestProfile` accepts a descriptor from
-`host.profileRoutes()` and routes that RPC through its exact registry source and
-profile without changing the active chat or gateway. The profile-only overload is
-retained only for the sole-local/legacy topology; registry-aware plugins should pass
-the descriptor so two sources exposing the same profile name cannot collide.
-
-`host.openWorkspace(id, { render, title?, minWidth?, onClose? })` docks a
-plugin-rendered view into the **main workspace zone** — the same center area
-session tiles and previews use — as a tab, and reveals it. Re-calling it with
-the same `id` refreshes the content in place and re-fronts the tab instead of
-opening a duplicate. Closing the tab (the tab's Close control or ⌘W) tears the
-registration down and fires your `onClose`; the returned disposer closes it
-programmatically. Feature-detect it (`typeof host.openWorkspace ===
-'function'`) and fall back to a regular contributed pane on older desktop
-builds — Bot Mode's group-chat rooms are the reference consumer (main-window
-takeover when available, in-panel view otherwise).
-
-`host.paneVisibility(paneId)` returns a readonly reactive atom that is `true`
-while a contributed pane is actually on screen: present in the layout tree,
-not dismissed or hidden, its zone un-minimized, and holding its zone's active
-tab slot (a lone pane in its own zone counts). The id is the
-contribution-scoped pane id, `<pluginId>:<paneId>`. Atoms are memoized per id,
-so calling it in render is safe. Use it to register companion UI only while
-your pane is visible — Bot Mode's Cronjobs pane is the reference consumer: it
-registers while the Bots pane holds the sidebar tab and unregisters when the
-user tabs back to Sessions. Feature-detect on older desktops
-(`typeof host.paneVisibility === 'function'`) and fall back to
-always-registered behavior.
-
-`host.profileRoutes()` inventories every registered source in the current connection
-registry. Connect-on-demand SSH sources expose a credential-free `default` seed
-route without opening a tunnel, so a plugin can be the first caller that dials them;
-an SSH `remoteProfile` remains the route's backend `targetProfile`. `connectionId`
-is the registry routing identity;
-pair it with `profile` for keys and persistence. Endpoint, token, SSH host/key, and
-other raw connection fields never cross the plugin IPC boundary. `profile` is the
-source-local route used
-for requests; `targetProfile` is the backend Hermes profile served by that route.
-They differ when a route explicitly maps to another backend profile (for example an
-SSH `remoteProfile` override or a legacy per-profile URL alias). This distinction
-preserves backend identity without exposing connection secrets.
-
-Profile-shaped plugins get first-class methods too:
-`profiles.list` (each profile + its most recent conversation as
-`last_session`; pass `include_sessions: false` to skip the per-profile DB
-probe; pass `preferred_session_ids: { profileName: sessionId }` for an
-exact, existence-checked lookup of one pinned session per profile — each
-named row gains a `preferred_session` summary that resolves hidden rows
-and compression lineages to their live tip, or `null` when the id is
-definitively gone; older gateways ignore the param and omit the field)
-and `profiles.create` (`name`, `description`, `clone_from`,
-`clone_all`, `no_skills`, `soul`, optional `model` + `provider` pin) — the
-ws twins of the dashboard's `/api/profiles` REST routes.
-`host.state.busy` is the focused chat's live turn (thinking and streaming).
-`host.state.awaitingResponse` stays true from send until the first assistant
-payload. Both follow the chat the user is actually looking at — the focused
-session tile when one holds focus, else the primary workspace chat (the same
-signal the statusbar's busy pulse reads). Subscribe in a component:
-
-```javascript
-const busy = useValue(host.state.busy)
-```
-
-For token-level detail, listen with `host.onEvent` (`message.start`,
-`message.delta`, `message.complete`).
-
-`host.onEvent` streams live gateway events (message deltas,
-session lifecycle, tool activity). Listeners are isolated — a throw in your
-listener can't affect app dispatch. Every `host` door is async-safe: a sync throw
-from an internal helper (e.g. no desktop bridge in a plain browser) becomes a
-rejection your `.catch()` sees, never an error-boundary crash.
-
-`ctx.os` is the curated OS door — every way a plugin reaches outside the app
-window, in one namespace attributed to your plugin. `ctx.os.notify` posts a
-**native OS notification** — the same Electron pipeline the app's own
-approval/turn alerts use. It fires only while the user is away from Hermes
-(backgrounded / unfocused); use `host.notify` for the in-app toast when
-they're looking at the app. Users can silence it per device under Settings ▸
-Notifications ▸ "Plugin notifications", and repeats from the same plugin are
-throttled, so treat it as a signal for genuinely notable events — not a log.
-
-Rich presentation + activation (extends the original `ctx.os` door):
-
-```ts
-ctx.os.notify({
-  title: 'New match found',
-  body: 'Someone matched your signal',
-  icon: '/abs/path/to/icon.png', // Electron Notification icon
-  // Body click → focus Hermes + navigate. Same vocabulary as OS deep links:
-  activate: 'hermes://index-network/intent/1',
-  // or: activate: '/index-network/intent/1'
-  // or: activate: { path: '/index-network/intent/1' }
-  onActivate: () => focusLocalState('1'), // optional renderer callback
-  actions: [
-    { id: 'open', label: 'Open', activate: 'hermes://index-network/intent/1' },
-    { id: 'dismiss', label: 'Dismiss', onAction: () => dismiss('1') },
-  ],
-})
-```
-
-`activate` is deeplink-compatible: `hermes://index-network/intent/1` and the
-hash path `/index-network/intent/1` resolve to the same in-app route (and the
-same `hermes://…` URL works as an OS deep link). Action buttons only render on
-signed macOS builds; elsewhere the body click still activates. Navigation only
-happens on user click — never from a background event alone.
-
-The other doors (`openExternal`, `revealPath`, `writeClipboard`) resolve
-`false` instead of throwing when the capability isn't available (older desktop
-shell, plain browser) — branch on the result rather than sniffing the bridge.
-
-## Data layer — React Query + nanostores
-
-Plugins share the app's single `QueryClient`, so plugin queries cache, dedupe,
-poll, and invalidate exactly like core screens — never hand-roll a fetch loop.
-
-```javascript
-import { useQuery, useMutation, useQueryClient, atom, computed, useValue } from '@hermes/plugin-sdk'
-
-function MyPanel() {
-  const { data, isLoading } = useQuery({
-    queryKey: ['my-plugin', 'items'],
-    queryFn: () => host.request('my.list', {})
-  })
-  // …
-}
-```
-
-For state shared between a trigger and its panel (or a poll loop), use `atom` /
-`computed` — the same primitive `host.state` uses. Subscribe in the leaf that
-renders the value with `useValue`. To invalidate a query from **outside** React
-(e.g. a `ctx.socket` frame arriving), import the shared `queryClient`:
-
-```javascript
-import { queryClient } from '@hermes/plugin-sdk'
-
-ctx.socket('/events', () => {
-  queryClient.invalidateQueries({ queryKey: ['my-plugin', 'items'] })
-})
-```
-
-## The UI kit and theming
-
-Import the app's real components directly so your UI is native by default:
-
-> `Button`, `Input`, `Textarea`, `Select*`, `Switch`, `Checkbox`,
-> `SegmentedControl`, `Tabs*`, `Dialog*`, `ConfirmDialog`, `DropdownMenu*`,
-> `ContextMenu*`, `Popover*`, `Tip`/`Tooltip*`, `Badge`, `Kbd`/`KbdGroup`,
-> `SearchField`, `ScrollArea`, `Separator`, `Skeleton`, `GlyphSpinner`, `Loader`,
-> `EmptyState`, `ErrorState`, `CopyButton`, `StatusDot`, `LogView`, `Codicon`,
-> `DecodeText`.
-
-Plus helpers: `cn` (class merge), `icons.*` (the app's lucide set), `haptic`,
-`profileColor` / `profileColorSoft` (deterministic identity colors), the time
-formatters `relativeTime` / `fmtDateTime` / `fmtDayTime` / `coarseElapsed`,
-`useI18n` (localized copy — your plugin stays translatable), and
-`evaluateRuntimeReadiness`.
-
-**Style with theme variables, never hardcoded colors.** Panes already sit on the
-app's editor background — leave the background alone and use vars for everything
-else: `var(--ui-text-secondary)`, `var(--ui-text-tertiary)`,
-`var(--ui-text-quaternary)`, `var(--ui-stroke-secondary)`, `var(--ui-accent)`.
-For canvas drawing, resolve them once with
-`getComputedStyle(canvas).getPropertyValue('--ui-accent')`. This is what makes a
-plugin reskin automatically with every theme.
-
-## A backend for your plugin
-
-If your plugin needs server-side work, ship a Python `plugin_api.py` and reach it
-through `ctx.rest` / `ctx.socket` — a namespace scoped to your plugin **by
-construction**.
-
-### One package, both SDKs {#one-package-both-sdks}
-
-A feature that needs a desktop UI **and** agent-side code (a Python plugin, its
-backend routes, skills) doesn't have to ship as two co-dependent installs. Put a
-`desktop/plugin.js` inside the agent package. When the package lands in any
-local `plugins/` root (default home or a profile), the Electron main process
-copies that half into `$HERMES_HOME/desktop-plugins/<id>/` beside a
-`.hermes-package.json` marker, and the renderer loads it through the exact same
-pipeline as the standalone disk door (hot reload included):
-
-```
-~/.hermes/plugins/<id>/           # ONE installable folder
-├── plugin.yaml                   # the agent half: tools, hooks, commands
-├── skills/…
-├── dashboard/
-│   ├── manifest.json             # { "name": "<id>", "api": "plugin_api.py" }
-│   └── plugin_api.py             # backend routes → /api/plugins/<id>/
-└── desktop/
-    └── plugin.js                 # the desktop half: panes, commands, ctx.rest
-```
-
-The `desktop/plugin.js` half is an ordinary disk plugin — same contract, same
-imports, same `ctx.rest('/…')` reaching the `plugin_api.py` sitting beside it.
-Installing, sharing, or removing the feature is one folder: the app-root copy
-is refreshed when the source `plugin.js` changes (`hermes plugins update`, or
-**Rescan**) and removed when the package folder disappears. The copy is what
-makes the desktop half **app-level**: it exists once, however many profiles
-carry the package, and it never appears or disappears when the user switches
-the Capabilities profile selector. The renderer never scans `plugins/` itself.
-The marker records the package name and its origin (catalog sidecar or git
-remote), which is what the **Install here** button on the Plugins page uses to
-install the agent half into another profile.
-
-Two enable switches still apply, on purpose, and both default to **off**: the
-desktop half ships opt-in — it inventories in **Capabilities → Plugins** but stays
-disabled until the user toggles it — matching the Python half's
-`plugins.enabled` gate in `config.yaml` (the security boundary below). Dropping
-a package into `~/.hermes/plugins` is inert on every surface until the user
-says otherwise. The desktop half degrades gracefully when the backend half is
-off — `ctx.rest` returns errors, not crashes.
-
-:::note
-The copy is local to the machine the desktop app runs on. Against a remote
-backend, the remote box's `~/.hermes/plugins` is not reachable as a filesystem —
-only locally installed packages contribute a desktop half this way. For a
-remote backend the install dialog clones the desktop half separately into
-`desktop-plugins/`, the same as a desktop-only repo.
-:::
-
-### Distributing with an install link {#install-link}
-
-Ship your plugin repo (agent half, desktop half, or both) and link to it with
-the `hermes://` scheme — a plain anchor on your website or README:
-
-```html
-<a href="hermes://plugin/install?repo=owner/repo&enable=1">Install in Hermes</a>
-```
-
-The user gets a confirmation dialog (repo id, source links, a probe of what
-the repo ships) and picks components before anything is installed — deep links
-never auto-install. `force=1` replaces an existing install; dev builds use
-`hermes-dev://`. Full link reference:
-[One-click install links](/user-guide/features/plugins#one-click-install-links-desktop).
-
-### The Python side
-
-Desktop plugins reuse the dashboard plugin backend mount. Put the backend in a
-`dashboard/` subfolder of a regular Hermes plugin and declare it in a
-`manifest.json`:
-
-```
-~/.hermes/plugins/<id>/
-└── dashboard/
-    ├── manifest.json      # { "name": "<id>", "api": "plugin_api.py" }
-    └── plugin_api.py      # exports `router = APIRouter()`
-```
-
-```python
-# plugin_api.py
-from fastapi import APIRouter
-
-router = APIRouter()
-
-@router.get("/board")
-async def board():
-    return {"items": ["one", "two", "three"]}
-
-@router.post("/action")
-async def action(body: dict):
-    return {"ok": True, "received": body}
-```
-
-Routes mount under `/api/plugins/<id>/` (`GET /api/plugins/<id>/board`, …).
-Backend code runs inside the gateway process, so it can import from the
-hermes-agent codebase directly (`hermes_state`, `hermes_cli.config`, …). See
-[Extending the Dashboard → Backend API routes](/user-guide/features/extending-the-dashboard#backend-api-routes)
-for the full backend reference — the mount is identical.
-
-:::caution The Python backend is gated separately
-Enabling a plugin in the desktop **Capabilities → Plugins** panel is a renderer-side
-choice; it does **not** import Python. A user plugin's `plugin_api.py` is
-imported only when the plugin is in the `plugins.enabled` allow-list in
-`config.yaml` (and not in `plugins.disabled`). Project plugins (`./.hermes/`)
-never auto-import Python. This is a security boundary, not an oversight
-(GHSA-mcfc-hp25-cjv7).
-:::
-
-### Calling it from the plugin
-
-```javascript
-register(ctx) {
-  // REST — namespace-relative path.
-  const load = () => ctx.rest('/board')                 // GET /api/plugins/<id>/board
-  const act  = () => ctx.rest('/action', { method: 'POST', body: { go: true } })
-
-  // Live twin — a WebSocket to your own namespace.
-  const stop = ctx.socket('/events', frame => {
-    queryClient.invalidateQueries({ queryKey: [ctx.source, 'board'] })
-  })
-}
-```
-
-`ctx.rest` is profile-aware and rejects path traversal (`..`) so you can never
-address another plugin's API or a core route through it. `PluginRestOptions` is
-`{ method?, body?, upload?: { filename, contentType?, bytes }, timeoutMs? }`.
-
-`ctx.socket` auto-reconnects with backoff until disposed. **It resolves to a no-op
-on OAuth remotes** (single-use WS tickets are core-managed) — treat the socket as
-an accelerator over polling, never a replacement. Every consumer needs a polling
-fallback anyway, since any socket can drop.
-
-For gateway-wide data (not your own namespace), use `host.request` (JSON-RPC) and
-`host.onEvent` (the gateway event stream) instead.
-
-## Settings, enable state, and storage
-
-Every plugin — enabled or not — inventories in **Capabilities → Plugins**, where the
-user toggles it live (no app restart), reveals its folder, or rescans. The user's
-choice is remembered:
-
-- No choice yet → the plugin's own `defaultEnabled` (default `true`). Set
-  `defaultEnabled: false` to ship an opt-in plugin that stays dark until the user
-  flips it on.
-- Explicit choice → persisted and honored across restarts. A disabled plugin
-  stays disabled — don't fight it; the user turned you off.
-
-Persist your own state with `ctx.storage`, namespaced to your plugin
-(`hermes.plugin.<id>.*`) so plugins can't read or clobber each other:
-
-```javascript
-ctx.storage.set('lastTab', 'board')
-const tab = ctx.storage.get('lastTab', 'summary')
-ctx.storage.remove('lastTab')
-```
-
-## Bundled plugins
-
-A plugin can ship in-tree at `apps/desktop/src/plugins/<id>/plugin.tsx` (default
-export a `HermesPlugin`). It's discovered by `discoverBundledPlugins()` at boot —
-no import, no registry edit — and shares the exact inventory + live
-enable/disable contract as a disk plugin. The two differences:
-
-1. It goes through the app's Vite build, so you can write **real JSX** and import
-   the SDK by its `@hermes/plugin-sdk` alias.
-2. It's still lint-fenced to `@hermes/plugin-sdk` + `react` only — no `@/…` app
-   internals.
-
-No desktop plugins ship in the core tree today; the shipped app stays uncluttered
-and demos live in the
-[`hermes-example-plugins`](https://github.com/NousResearch/hermes-example-plugins)
-companion repo.
-
-## Security model
-
-A loaded plugin is evaluated as ESM in the renderer realm with **full app
-authority** — the React singleton, the whole SDK (`host.request` gateway RPC,
-`ctx.rest`, storage, `navigate`). The isolation the loader provides is **error
-isolation only**: a plugin can't crash the app (contributions are error-bounded,
-listeners isolated), but it can do anything the app can.
-
-This is acceptable for **local** sources — a disk file can already run code on
-your machine — which is why the disk door only loads local files you (or your
-agent) wrote. The optional `integrity` (`sha256-…`) check only proves the bytes
-match a hash; it does **not** sandbox. A future remote-source door will need a
-real boundary (iframe/worker + CSP + capability gating) before it can land; do
-not treat this pipeline as a trust boundary.
-
-## Pitfalls
-
-- **JSX won't parse in a disk plugin.** The file loads uncompiled — use `jsx()` /
-  `jsxs()` (or `React.createElement`), not JSX syntax. (Bundled plugins are built,
-  so JSX is fine there.)
-- **Only three specifiers resolve:** `@hermes/plugin-sdk`, `react`,
-  `react/jsx-runtime`. Any other import surfaces an up-front load error.
-- **Never hardcode colors** (`#000`, `black`, `rgb(...)`). Leave the background
-  alone; use theme variables (`var(--ui-*)`) for everything.
-- **Reference only what you imported.** A component you forgot to import (e.g.
-  `StatusDot`) is a `ReferenceError` at render — double-check every identifier in
-  your `jsx()` calls appears in the import line.
-- **Read state imperatively in handlers** (`$atom.get()`), never from a render
-  closure — rapid events will otherwise see stale values. Subscribe (`useValue`)
-  only in the leaf that renders the value.
-- **Canvas panes must track their container** with a `ResizeObserver` and resize
-  the canvas (width/height attributes, not just CSS) — panes resize constantly.
-- **Don't poll faster than a few seconds** with `host.request`; prefer
-  `host.onEvent` / `ctx.socket` and let React Query dedupe.
-- **`ctx.socket` is a no-op on OAuth remotes.** Always have a polling fallback.
-
-## Reference
-
-### SDK exports at a glance
-
-| Category | Exports |
-|----------|---------|
-| Host | `host` (`.state.*`, `.notify`, `.notifyError`, `.navigate`, `.onEvent`, `.logs`, `.status`, `.restartGateway`, `.request`) |
-| Plugin contract | `HermesPlugin`, `PluginContext`, `PluginContribution`, `PluginStorage`, `PluginOs`, `PluginRestOptions`, `PluginNativeNotificationInput`, `PluginNotificationAction`, `HermesOpenTarget`, `Contribution` |
-| Area constants | `PANES_AREA`, `ROUTES_AREA`, `SIDEBAR_NAV_AREA`, `STATUSBAR_AREAS`, `TITLEBAR_AREAS`, `PALETTE_AREA`, `KEYBINDS_AREA`, `THEMES_AREA`, `COMPOSER_AREAS` |
-| Area payloads | `RouteContribution`, `SidebarNavContribution`, `StatusbarItem`, `TitlebarTool`, `PaletteContribution`, `KeybindContribution`, `ComposerMiddleware`, `ComposerAttachmentProvider` |
-| React / state | `useValue`, `atom`, `computed`, `useQuery`, `useMutation`, `useQueryClient`, `queryClient`, `Contribute` |
-| Theming | `useTheme`, `requestTheme`, `setAccentOverride`, `$accentOverride`, `retintTheme`, `themeHue`, `DesktopTheme`, `DesktopThemeColors`, plus OKLCH math (`hexToOklch`, `oklchToHex`, `oklchToSrgb255`, `mixOklab`, `maxChroma`, `hueDelta`, `normalizeHex`) and sRGB measures (`contrastRatio` — `number | null`, null for unparseable input — `readableOn`) |
-| UI kit | `Button`, `Input`, `Textarea`, `Select*`, `Switch`, `Checkbox`, `SegmentedControl`, `Tabs*`, `Dialog*`, `ConfirmDialog`, `DropdownMenu*`, `ContextMenu*`, `Popover*`, `Tip`/`Tooltip*`, `Badge`, `Kbd`/`KbdGroup`, `SearchField`, `ScrollArea`, `Separator`, `Skeleton`, `GlyphSpinner`, `Loader`, `EmptyState`, `ErrorState`, `CopyButton`, `StatusDot`, `LogView`, `Codicon`, `DecodeText` |
-| Helpers | `cn`, `icons`, `haptic`, `useI18n`, `profileColor`, `profileColorSoft`, `relativeTime`, `fmtDateTime`, `fmtDayTime`, `coarseElapsed`, `evaluateRuntimeReadiness` |
-
-The canonical, always-current export list is `apps/desktop/src/sdk/index.ts`.
-
-### Agents: the `hermes-desktop-plugins` skill
-
-When an agent writes a desktop plugin, it should load the bundled
-**`hermes-desktop-plugins`** skill — it carries the same contract as this page in
-agent-facing form, with a ready-to-copy `templates/plugin.js`. This page is the
-human/developer reference; the skill is the working checklist.
-
-## Troubleshooting
-
-**My plugin doesn't appear.** Confirm the file is at
-`$HERMES_HOME/desktop-plugins/<id>/plugin.js` and the folder name matches the
-export `id`. Run ⌘K → **Reload desktop plugins**. Check the app for an error
-toast naming the failure, and tail `hermes logs gui -f`.
-
-**"unsupported import" on load.** A disk plugin may only import
-`@hermes/plugin-sdk`, `react`, and `react/jsx-runtime`. Remove any other import.
-
-**A `jsx` element renders nothing / throws `ReferenceError`.** An identifier used
-in a `jsx()` call isn't imported. Add it to the import line.
-
-**`ctx.rest` returns 404.** The backend isn't mounted: confirm
-`~/.hermes/plugins/<id>/dashboard/manifest.json` has `"api": "plugin_api.py"`,
-that the plugin is in `plugins.enabled` in `config.yaml`, and restart the gateway
-(backend routes mount at startup). Tail `~/.hermes/logs/errors.log` for
-`Failed to load plugin <id> API routes`.
-
-**`ctx.socket` never fires.** On an OAuth remote it's a no-op by design — use your
-polling fallback. Otherwise verify the backend exposes the matching
-`@router.websocket(...)` route under its namespace.
-
-**Colors look wrong after a theme switch.** You hardcoded a color. Replace it with
-a `var(--ui-*)` theme variable.