feat(desktop): agent plugins in Settings → Plugins

Backend plugins — native Hermes plugins and portable Agent Plugins v1
packages — were invisible in the desktop app. Settings → Plugins now
lists them under the desktop (renderer) plugins with source/portable
pills, enable/disable switches keyed by canonical registry key, and a
live-filter search box, backed by a nanostore over plugins.manage.
Categories other surfaces own (dashboard_auth/*, model-providers/*,
platforms/*) are curated out renderer-side.
This commit is contained in:
Brooklyn Nicholson
2026-08-08 17:24:59 -05:00
parent a60b492e07
commit c86da8397b
5 changed files with 345 additions and 39 deletions
@@ -1,5 +1,7 @@
import { useStore } from '@nanostores/react'
import { type ReactNode, useEffect, useState } from 'react'
import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
import { Button } from '@/components/ui/button'
import { Codicon } from '@/components/ui/codicon'
import { Switch } from '@/components/ui/switch'
@@ -8,13 +10,37 @@ import { $pluginRecords, type PluginRecord, setPluginEnabled } from '@/contrib/p
import { discoverRuntimePlugins } from '@/contrib/runtime-loader'
import { useI18n } from '@/i18n'
import { triggerHaptic } from '@/lib/haptics'
import { Package } from '@/lib/icons'
import { FolderOpen, Monitor, Package, RefreshCw } from '@/lib/icons'
import { normalize } from '@/lib/text'
import {
$agentPluginBusy,
$agentPlugins,
$agentPluginsError,
$agentPluginsStatus,
type AgentPluginRow,
loadAgentPlugins,
toggleAgentPlugin
} from '@/store/agent-plugins'
import { notifyError } from '@/store/notifications'
import { $gatewayState } from '@/store/session'
import { EmptyState, ListRow, Pill, SectionHeading, SettingsContent } from './primitives'
import { EmptyState, ListRowSkeleton, Pill, SettingsContent, SettingsSection } from './primitives'
const KIND_ORDER: Record<PluginRecord['kind'], number> = { disk: 0, runtime: 1, bundled: 2 }
// User-installed plugins first, bundled last — mirrors `hermes plugins list`.
const SOURCE_ORDER: Record<string, number> = { user: 0, git: 0, project: 1, entrypoint: 2, bundled: 3 }
// Plugin categories (by registry key prefix) that other surfaces own — same
// curation stance as desktop-slash-commands.ts. dashboard_auth/* only matters
// to `hermes dashboard`; model-providers/* are configured in Settings →
// Models; platforms/* are managed from Messaging. The plugin switch is not
// the user-facing control for any of them, so listing them here is noise.
const HIDDEN_KEY_PREFIXES = ['dashboard_auth/', 'model-providers/', 'platforms/']
const isDesktopRelevant = (row: AgentPluginRow) =>
!HIDDEN_KEY_PREFIXES.some(prefix => row.key.startsWith(prefix))
function reveal(file: string) {
void window.hermesDesktop?.revealPath?.(file)?.catch(() => undefined)
}
@@ -43,14 +69,145 @@ async function revealPluginsDir() {
}
}
// Compact row: name + pills and a wrapping description on the left, controls
// pinned top-right. Same type scale as ListRow, without its wide control grid.
function PluginLine({
title,
description,
controls
}: {
title: ReactNode
description?: ReactNode
controls: ReactNode
}) {
return (
<div className="flex items-start gap-3 py-2">
<div className="min-w-0 flex-1 pr-4">
<div className="flex flex-wrap items-center gap-2 text-[length:var(--conversation-text-font-size)] font-medium text-foreground">
{title}
</div>
{description && (
<div className="mt-0.5 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) break-words text-(--ui-text-tertiary)">
{description}
</div>
)}
</div>
<div className="flex shrink-0 items-center gap-2">{controls}</div>
</div>
)
}
function AgentPluginRowView({ row }: { row: AgentPluginRow }) {
const { t } = useI18n()
const p = t.settings.plugins
const { requestGateway } = useGatewayRequest()
const busy = useStore($agentPluginBusy)
return (
<PluginLine
controls={
<Switch
aria-label={`${row.status === 'enabled' ? p.disable : p.enable} ${row.name}`}
checked={row.status === 'enabled'}
disabled={busy === row.key}
onCheckedChange={on => {
triggerHaptic('selection')
void toggleAgentPlugin(requestGateway, row.key, on, p.agent.toggleFailed(row.name))
}}
/>
}
description={row.description || (row.version ? `v${row.version}` : undefined)}
title={
<>
<span>{row.name}</span>
<Pill>{p.agent.sources[row.source] ?? row.source}</Pill>
{row.portable && <Pill tone="primary">{p.agent.portable}</Pill>}
</>
}
/>
)
}
function AgentPluginsSection() {
const { t } = useI18n()
const p = t.settings.plugins
const { requestGateway } = useGatewayRequest()
const gatewayState = useStore($gatewayState)
const rows = useStore($agentPlugins)
const status = useStore($agentPluginsStatus)
const error = useStore($agentPluginsError)
const [query, setQuery] = useState('')
useEffect(() => {
if (gatewayState !== 'open') {
return
}
void loadAgentPlugins(requestGateway)
}, [gatewayState, requestGateway])
const needle = normalize(query)
const sorted = rows
.filter(isDesktopRelevant)
.filter(
row =>
!needle ||
row.name.toLowerCase().includes(needle) ||
row.key.toLowerCase().includes(needle) ||
row.description.toLowerCase().includes(needle)
)
.sort((a, b) => (SOURCE_ORDER[a.source] ?? 9) - (SOURCE_ORDER[b.source] ?? 9) || a.name.localeCompare(b.name))
return (
<SettingsSection icon={Package} meta={status === 'ready' ? p.count(sorted.length) : undefined} title={p.agent.title}>
<p className="mb-2 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
{p.agent.blurb}
</p>
<input
className="mb-2 w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
onChange={event => setQuery(event.target.value)}
placeholder={p.agent.search}
spellCheck={false}
value={query}
/>
{status === 'loading' || status === 'idle' ? (
<div>
<ListRowSkeleton />
<ListRowSkeleton />
<ListRowSkeleton />
</div>
) : status === 'error' ? (
<EmptyState description={error ?? undefined} title={p.agent.loadFailed} />
) : sorted.length === 0 ? (
needle ? (
<p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
{p.agent.noMatches}
</p>
) : (
<EmptyState title={p.agent.empty} />
)
) : (
<div>
{sorted.map(row => (
<AgentPluginRowView key={row.key || row.name} row={row} />
))}
</div>
)}
</SettingsSection>
)
}
function PluginRow({ record }: { record: PluginRecord }) {
const { t } = useI18n()
const p = t.settings.plugins
return (
<ListRow
action={
<div className="flex items-center justify-end gap-2">
<PluginLine
controls={
<>
{record.file && (
<Tip label={p.reveal}>
<Button onClick={() => reveal(record.file!)} size="icon" variant="ghost">
@@ -66,7 +223,7 @@ function PluginRow({ record }: { record: PluginRecord }) {
void setPluginEnabled(record.id, on)
}}
/>
</div>
</>
}
description={
record.status === 'error' ? (
@@ -76,11 +233,11 @@ function PluginRow({ record }: { record: PluginRecord }) {
)
}
title={
<span className="flex items-center gap-2">
{record.name}
<>
<span>{record.name}</span>
<Pill>{p.kinds[record.kind]}</Pill>
{record.status === 'error' && <Pill tone="primary">{p.failed}</Pill>}
</span>
</>
}
/>
)
@@ -97,36 +254,40 @@ export function PluginsSettings() {
return (
<SettingsContent>
<SectionHeading icon={Package} meta={p.count(rows.length)} title={p.title} />
<p className="mb-4 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">{p.blurb}</p>
<SettingsSection icon={Monitor} meta={p.count(rows.length)} title={p.title}>
<p className="mb-2 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">{p.blurb}</p>
<div className="mb-4 flex items-center gap-2">
<Button onClick={() => void revealPluginsDir()} size="sm" variant="outline">
<Codicon name="folder-opened" size="0.8rem" />
{p.openFolder}
</Button>
<Button
onClick={() => {
triggerHaptic('selection')
void discoverRuntimePlugins()
}}
size="sm"
variant="outline"
>
<Codicon name="refresh" size="0.8rem" />
{p.rescan}
</Button>
</div>
{rows.length === 0 ? (
<EmptyState title={p.empty} />
) : (
<div className="divide-y divide-(--ui-stroke-tertiary)">
{rows.map(record => (
<PluginRow key={record.id} record={record} />
))}
<div className="mb-2 flex items-center gap-3">
<Button onClick={() => void revealPluginsDir()} size="sm" type="button" variant="textStrong">
<FolderOpen className="size-3.5" />
<span>{p.openFolder}</span>
</Button>
<Button
onClick={() => {
triggerHaptic('selection')
void discoverRuntimePlugins()
}}
size="sm"
type="button"
variant="textStrong"
>
<RefreshCw className="size-3.5" />
<span>{p.rescan}</span>
</Button>
</div>
)}
{rows.length === 0 ? (
<EmptyState title={p.empty} />
) : (
<div>
{rows.map(record => (
<PluginRow key={record.id} record={record} />
))}
</div>
)}
</SettingsSection>
<AgentPluginsSection />
</SettingsContent>
)
}
+13 -1
View File
@@ -365,7 +365,19 @@ export const en: Translations = {
disable: 'Disable',
failed: 'failed',
empty: 'No desktop plugins installed yet.',
kinds: { bundled: 'bundled', disk: 'on disk', runtime: 'runtime' }
kinds: { bundled: 'bundled', disk: 'on disk', runtime: 'runtime' },
agent: {
title: 'Agent plugins',
blurb:
'Run in the Hermes backend — tools, skills, MCP servers, hooks, and slash commands. Portable ones are Agent Plugins packages (skills + MCP bundles that work in other agents too). Toggles apply to new sessions.',
empty: 'No agent plugins installed yet.',
loadFailed: 'Could not load agent plugins',
portable: 'portable',
search: 'Search plugins…',
noMatches: 'No plugins match your search.',
toggleFailed: (name: string) => `Could not toggle ${name}`,
sources: { bundled: 'bundled', user: 'user', git: 'git', project: 'project', entrypoint: 'pip' }
}
},
notifications: {
title: 'Notifications',
+11
View File
@@ -317,6 +317,17 @@ export interface Translations {
failed: string
empty: string
kinds: { bundled: string; disk: string; runtime: string }
agent: {
title: string
blurb: string
empty: string
loadFailed: string
portable: string
search: string
noMatches: string
toggleFailed: (name: string) => string
sources: Record<string, string>
}
}
notifications: {
title: string
+13 -1
View File
@@ -356,7 +356,19 @@ export const zh: Translations = {
disable: '禁用',
failed: '失败',
empty: '尚未安装桌面插件。',
kinds: { bundled: '内置', disk: '磁盘', runtime: '运行时' }
kinds: { bundled: '内置', disk: '磁盘', runtime: '运行时' },
agent: {
title: '智能体插件',
blurb:
'运行在 Hermes 后端——工具、技能、MCP 服务器、钩子和斜杠命令。「便携」插件是 Agent Plugins 标准包(技能 + MCP 组合,也可在其他智能体中使用)。开关在新会话中生效。',
empty: '尚未安装智能体插件。',
loadFailed: '无法加载智能体插件',
portable: '便携',
search: '搜索插件…',
noMatches: '没有匹配的插件。',
toggleFailed: (name: string) => `无法切换 ${name}`,
sources: { bundled: '内置', user: '用户', git: 'git', project: '项目', entrypoint: 'pip' }
}
},
notifications: {
title: '通知',
+110
View File
@@ -0,0 +1,110 @@
import { atom } from 'nanostores'
import { notifyError } from '@/store/notifications'
/**
* Feature store for backend (agent) plugins — the native Hermes plugins plus
* portable Agent Plugins v1 packages the backend discovers on disk. Settings
* renders this next to the desktop (renderer) plugin inventory so every plugin
* the user has is discoverable and toggleable from one page, whatever process
* it runs in.
*
* Backed by the gateway's `plugins.manage` RPC — the same list/toggle
* primitives `hermes plugins` and the dashboard use, so all surfaces agree on
* what's installed and what's enabled. Works against every backend topology
* (local spawn, SSH, URL+token) because it rides the session's own transport.
*/
export interface AgentPluginRow {
name: string
/** Canonical registry key (e.g. `image_gen/fal`) — names can collide. */
key: string
version: string
description: string
/** 'bundled' | 'user' | 'git' | 'project' | 'entrypoint' */
source: string
status: 'enabled' | 'disabled' | 'not enabled'
/** Agent Plugins v1 package (portable skills/MCP format) vs native Hermes. */
portable?: boolean
}
export type AgentPluginsStatus = 'idle' | 'loading' | 'ready' | 'error'
/** The recovering `requestGateway` from `useGatewayRequest`. */
export type GatewayRequest = <T>(method: string, params?: Record<string, unknown>) => Promise<T>
export const $agentPlugins = atom<AgentPluginRow[]>([])
export const $agentPluginsStatus = atom<AgentPluginsStatus>('idle')
export const $agentPluginsError = atom<string | null>(null)
/** Key of the row whose toggle RPC is in flight (disables its switch). */
export const $agentPluginBusy = atom<string | null>(null)
let inflight: Promise<void> | null = null
/** Fetch the backend plugin list. Always refetches (it's a cheap local disk
* scan on the backend); concurrent callers share one in-flight request. */
export function loadAgentPlugins(request: GatewayRequest): Promise<void> {
if (inflight) {
return inflight
}
inflight = (async () => {
if ($agentPluginsStatus.get() !== 'ready') {
$agentPluginsStatus.set('loading')
}
try {
const result = await request<{ plugins?: AgentPluginRow[] }>('plugins.manage', { action: 'list' })
$agentPlugins.set(result?.plugins ?? [])
$agentPluginsStatus.set('ready')
$agentPluginsError.set(null)
} catch (e) {
$agentPluginsError.set(e instanceof Error ? e.message : String(e))
$agentPluginsStatus.set('error')
} finally {
inflight = null
}
})()
return inflight
}
/** Flip a backend plugin on/off and patch the row from the RPC's refreshed
* copy. Addressed by canonical key — bare names collide (image_gen/fal vs
* video_gen/fal). Returns whether the toggle stuck. */
export async function toggleAgentPlugin(
request: GatewayRequest,
key: string,
enable: boolean,
failMessage: string
): Promise<boolean> {
$agentPluginBusy.set(key)
try {
const result = await request<{ ok?: boolean; plugin?: AgentPluginRow | null }>('plugins.manage', {
action: 'toggle',
key,
enable
})
if (!result?.ok) {
throw new Error(failMessage)
}
const refreshed = result.plugin
if (refreshed) {
$agentPlugins.set($agentPlugins.get().map(row => (row.key === key ? { ...row, ...refreshed } : row)))
} else {
await loadAgentPlugins(request)
}
return true
} catch (e) {
notifyError(e, failMessage)
return false
} finally {
$agentPluginBusy.set(null)
}
}