🙌 OpenHands: AI-Driven Development
feat: show locally-discovered plugins as a read-only Local group (#1616)
Hiep Le27111e154d76
diff --git a/__tests__/components/features/plugins/build-plugins-view-model.test.ts b/__tests__/components/features/plugins/build-plugins-view-model.test.tsindex 2a25150eb3..4a559c4ce1 100644--- a/__tests__/components/features/plugins/build-plugins-view-model.test.ts+++ b/__tests__/components/features/plugins/build-plugins-view-model.test.ts@@ -1,6 +1,9 @@import { describe, expect, it } from "vitest";-import { buildPluginsViewModel } from "#/components/features/plugins/build-plugins-view-model";-import type { MarketplacePlugin } from "#/api/plugins-service";+import {+ buildPluginsViewModel,+ matchesPluginStatus,+} from "#/components/features/plugins/build-plugins-view-model";+import type { MarketplacePlugin, LocalPlugin } from "#/api/plugins-service";import type { InstalledPluginInfo } from "#/api/plugins-management-service";const catalogPlugin: MarketplacePlugin = {@@ -24,6 +27,12 @@ const installedPlugin: InstalledPluginInfo = {install_path: "/home/.openhands/plugins/installed/demo-plugin",};+const localPlugin: LocalPlugin = {+ name: "ambient-plugin",+ version: "1.0.0",+ description: "Ambient description",+};+describe("buildPluginsViewModel", () => {it("merges a plugin present in both the catalog and the installed list into one installed entry", () => {const result = buildPluginsViewModel([catalogPlugin], [installedPlugin]);@@ -60,4 +69,39 @@ describe("buildPluginsViewModel", () => {enabled: false,});});++ it("adds a locally-discovered plugin as a read-only local entry", () => {+ const result = buildPluginsViewModel([], [], [localPlugin]);++ expect(result).toHaveLength(1);+ expect(result[0]).toMatchObject({+ name: "ambient-plugin",+ isLocal: true,+ installed: false,+ inCatalog: false,+ version: "1.0.0",+ });+ });++ it("does not add a separate local entry when the plugin is already installed", () => {+ const result = buildPluginsViewModel(+ [],+ [installedPlugin],+ [{ ...localPlugin, name: installedPlugin.name }],+ );++ expect(result).toHaveLength(1);+ expect(result[0]).toMatchObject({+ name: "demo-plugin",+ installed: true,+ isLocal: false,+ });+ });++ it("classifies a local plugin under the local filter and not the available filter", () => {+ const [local] = buildPluginsViewModel([], [], [localPlugin]);++ expect(matchesPluginStatus(local, "local")).toBe(true);+ expect(matchesPluginStatus(local, "available")).toBe(false);+ });});diff --git a/__tests__/routes/plugins-page.test.tsx b/__tests__/routes/plugins-page.test.tsxindex 3cf4057248..f95e7b5537 100644--- a/__tests__/routes/plugins-page.test.tsx+++ b/__tests__/routes/plugins-page.test.tsx@@ -93,6 +93,7 @@ describe("SkillsPluginsScreen", () => {MOCK_DEFAULT_USER_SETTINGS,);vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([]);+ vi.spyOn(PluginsService, "getLocalPlugins").mockResolvedValue([]);vi.spyOn(PluginsManagementService,"listInstalledPlugins",@@ -208,6 +209,24 @@ describe("SkillsPluginsScreen", () => {expect(await screen.findByTestId("plugins-empty")).toBeInTheDocument();});+ it("renders a local plugin as a read-only card without install or toggle controls", async () => {+ vi.spyOn(PluginsService, "getLocalPlugins").mockResolvedValue([+ { name: "ambient-plugin", version: "1.0.0", description: "Ambient" },+ ]);++ renderPluginsScreen();++ expect(+ await screen.findByTestId("plugin-local-badge-ambient-plugin"),+ ).toBeInTheDocument();+ expect(+ screen.queryByTestId("plugin-install-ambient-plugin"),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByTestId("plugin-toggle-ambient-plugin"),+ ).not.toBeInTheDocument();+ });+it("shows the no-match state when the search excludes everything", async () => {vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([buildCatalogPlugin(),diff --git a/src/api/plugins-service.test.ts b/src/api/plugins-service.test.tsindex fbc150155b..d9e0923d82 100644--- a/src/api/plugins-service.test.ts+++ b/src/api/plugins-service.test.ts@@ -11,6 +11,7 @@ vi.mock("@openhands/typescript-client/clients", () => ({}));const getPluginsMarketplace = vi.fn();+const getPlugins = vi.fn();const close = vi.fn();function useBackend(kind: "local" | "cloud"): void {@@ -70,3 +71,39 @@ describe("PluginsService.getPluginsMarketplace", () => {expect(result).toEqual([]);});});++describe("PluginsService.getLocalPlugins", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ vi.mocked(PluginsClient).mockImplementation(function MockPluginsClient() {+ return { getPlugins, close } as unknown as PluginsClient;+ } as unknown as typeof PluginsClient);+ });++ it("requests user-level local plugins from the local agent-server", async () => {+ useBackend("local");+ const plugin = {+ name: "hello-local",+ version: "1.0.0",+ description: "A local plugin",+ };+ getPlugins.mockResolvedValue({ plugins: [plugin] });++ const result = await PluginsService.getLocalPlugins();++ expect(result).toEqual([plugin]);+ expect(getPlugins).toHaveBeenCalledWith({+ load_user: true,+ load_project: false,+ });+ });++ it("returns an empty list on a cloud backend without calling the client", async () => {+ useBackend("cloud");++ const result = await PluginsService.getLocalPlugins();++ expect(result).toEqual([]);+ expect(PluginsClient).not.toHaveBeenCalled();+ });+});diff --git a/src/api/plugins-service.ts b/src/api/plugins-service.tsindex daadb7ef39..5522e0ca49 100644--- a/src/api/plugins-service.ts+++ b/src/api/plugins-service.ts@@ -16,6 +16,19 @@ export interface MarketplacePlugin {installed: boolean;}+/**+ * A locally-discovered ("ambient") plugin reported by the agent-server — one+ * found in the user's local plugin directories (e.g. `~/.agents/plugins`).+ * These auto-load into conversations and are not managed via install/uninstall,+ * so the Plugins page renders them as a read-only "Local" group. Matches the+ * typescript-client `PluginInfo`.+ */+export interface LocalPlugin {+ name: string;+ version: string;+ description: string;+}+class PluginsService {/*** Fetch the dynamic plugins marketplace catalog.@@ -41,6 +54,32 @@ class PluginsService {return [];}}++ /**+ * Fetch the locally-discovered ("ambient") plugins from the agent-server.+ *+ * Only user-level plugins are requested (`~/.agents/plugins`,+ * `~/.openhands/plugins`, plus enabled installed plugins): the Plugins page is+ * global, so there is no project workspace to scope project plugins to.+ *+ * Local backend only — a cloud backend has no local plugin directories, so an+ * empty list is returned. Errors surface as an empty list (mirrors the+ * catalog) rather than throwing.+ */+ static async getLocalPlugins(): Promise<LocalPlugin[]> {+ if (getActiveBackend().backend.kind === "cloud") {+ return [];+ }++ try {+ const response = await new PluginsClient(+ getAgentServerClientOptions(),+ ).getPlugins({ load_user: true, load_project: false });+ return (response.plugins ?? []) as LocalPlugin[];+ } catch {+ return [];+ }+ }}export default PluginsService;diff --git a/src/components/features/plugins/build-plugins-view-model.ts b/src/components/features/plugins/build-plugins-view-model.tsindex 2c816dd2a6..7483440860 100644--- a/src/components/features/plugins/build-plugins-view-model.ts+++ b/src/components/features/plugins/build-plugins-view-model.ts@@ -1,7 +1,7 @@-import type { MarketplacePlugin } from "#/api/plugins-service";+import type { MarketplacePlugin, LocalPlugin } from "#/api/plugins-service";import type { InstalledPluginInfo } from "#/api/plugins-management-service";-export type PluginStatusFilter = "all" | "installed" | "available";+export type PluginStatusFilter = "all" | "installed" | "available" | "local";/*** A single row in the plugins management list, reconciling the dynamic@@ -21,6 +21,11 @@ export interface PluginViewModel {version: string | null;/** Present in the marketplace catalog. */inCatalog: boolean;+ /**+ * Discovered from a local ambient directory (e.g. `~/.agents/plugins`).+ * Read-only: it auto-loads into conversations and is not installed/managed.+ */+ isLocal: boolean;}/**@@ -33,6 +38,7 @@ export interface PluginViewModel {export function buildPluginsViewModel(marketplace: MarketplacePlugin[] | undefined,installed: InstalledPluginInfo[] | undefined,+ local: LocalPlugin[] | undefined = undefined,): PluginViewModel[] {const byName = new Map<string, PluginViewModel>();@@ -47,6 +53,7 @@ export function buildPluginsViewModel(enabled: false,version: null,inCatalog: true,+ isLocal: false,});}@@ -62,11 +69,37 @@ export function buildPluginsViewModel(enabled: entry.enabled,version: entry.version ?? null,inCatalog: existing?.inCatalog ?? false,+ isLocal: false,});}+ // Ambient local plugins are additive and read-only. A local plugin whose name+ // is already installed or in the catalog is skipped — that managed entry is+ // authoritative (the agent-server also folds enabled installed plugins into+ // this list), so it must not spawn a duplicate read-only "Local" card.+ for (const entry of local ?? []) {+ if (byName.has(entry.name)) continue;+ byName.set(entry.name, {+ name: entry.name,+ description: entry.description || null,+ source: null,+ ref: null,+ repoPath: null,+ installed: false,+ enabled: false,+ version: entry.version || null,+ inCatalog: false,+ isLocal: true,+ });+ }++ // Sort installed first, then local, then available; alphabetical within each.+ const rank = (plugin: PluginViewModel): number =>+ plugin.installed ? 0 : plugin.isLocal ? 1 : 2;+return Array.from(byName.values()).sort((a, b) => {- if (a.installed !== b.installed) return a.installed ? -1 : 1;+ const rankDelta = rank(a) - rank(b);+ if (rankDelta !== 0) return rankDelta;return a.name.localeCompare(b.name);});}@@ -94,6 +127,10 @@ export function matchesPluginStatus(filter: PluginStatusFilter,): boolean {if (filter === "installed") return plugin.installed;- if (filter === "available") return !plugin.installed;+ // "Available" means installable from the catalog; local plugins are neither+ // installed nor installable, so they are excluded here and grouped under+ // "local" instead.+ if (filter === "available") return !plugin.installed && !plugin.isLocal;+ if (filter === "local") return plugin.isLocal;return true;}diff --git a/src/components/features/plugins/plugin-card.tsx b/src/components/features/plugins/plugin-card.tsxindex 89cf69e99c..1152eca5f8 100644--- a/src/components/features/plugins/plugin-card.tsx+++ b/src/components/features/plugins/plugin-card.tsx@@ -84,6 +84,13 @@ export function PluginCard({onToggle={onToggle}disableTooltipKey={I18nKey.COMMON$DISABLE}/>+ ) : plugin.isLocal ? (+ <span+ data-testid={`plugin-local-badge-${plugin.name}`}+ className={cn(extensionModuleCardPillClassName, "flex-shrink-0")}+ >+ {t(I18nKey.SETTINGS$PLUGINS_FILTER_LOCAL)}+ </span>) : (<BrandButtontype="button"@@ -111,7 +118,7 @@ export function PluginCard({</p>) : null}- {plugin.installed && plugin.version ? (+ {(plugin.installed || plugin.isLocal) && plugin.version ? (<spandata-testid={`plugin-version-${plugin.name}`}className={cn(extensionModuleCardPillClassName, "self-start")}diff --git a/src/components/features/plugins/plugin-detail-modal.tsx b/src/components/features/plugins/plugin-detail-modal.tsxindex d2f5385089..9011ddf1bf 100644--- a/src/components/features/plugins/plugin-detail-modal.tsx+++ b/src/components/features/plugins/plugin-detail-modal.tsx@@ -62,6 +62,11 @@ export function PluginDetailModal({) : null}<div className="flex flex-wrap gap-2">+ {plugin.isLocal ? (+ <span className={extensionModuleCardPillClassName}>+ {t(I18nKey.SETTINGS$PLUGINS_FILTER_LOCAL)}+ </span>+ ) : null}{plugin.version ? (<span className={extensionModuleCardPillClassName}>{t(I18nKey.SETTINGS$SKILLS_VERSION, {@@ -120,7 +125,7 @@ export function PluginDetailModal({{t(I18nKey.SETTINGS$PLUGINS_UNINSTALL)}</BrandButton></>- ) : (+ ) : plugin.isLocal ? null : (<BrandButtontype="button"variant="primary"diff --git a/src/components/features/plugins/plugins-toolbar.tsx b/src/components/features/plugins/plugins-toolbar.tsxindex 93ed064b4b..146a0b5f72 100644--- a/src/components/features/plugins/plugins-toolbar.tsx+++ b/src/components/features/plugins/plugins-toolbar.tsx@@ -18,6 +18,7 @@ const STATUS_FILTERS: ReadonlyArray<{{ value: "all", labelKey: I18nKey.SETTINGS$PLUGINS_FILTER_ALL },{ value: "installed", labelKey: I18nKey.SETTINGS$PLUGINS_FILTER_INSTALLED },{ value: "available", labelKey: I18nKey.SETTINGS$PLUGINS_FILTER_AVAILABLE },+ { value: "local", labelKey: I18nKey.SETTINGS$PLUGINS_FILTER_LOCAL },];export function PluginsToolbar({diff --git a/src/hooks/query/query-keys.ts b/src/hooks/query/query-keys.tsindex fdb9f74c42..cd602d7326 100644--- a/src/hooks/query/query-keys.ts+++ b/src/hooks/query/query-keys.ts@@ -35,6 +35,8 @@ export const PLUGINS_QUERY_KEYS = {marketplace: ["plugins-marketplace"] as const,/** Installed plugins from the local agent-server. */installed: ["plugins-installed"] as const,+ /** Locally-discovered ambient plugins (used by `use-local-plugins`). */+ local: ["plugins-local"] as const,} as const;/** Cache configuration shared across all config-related queries */diff --git a/src/hooks/query/use-local-plugins.ts b/src/hooks/query/use-local-plugins.tsnew file mode 100644index 0000000000..5a3db52c15--- /dev/null+++ b/src/hooks/query/use-local-plugins.ts@@ -0,0 +1,17 @@+import { useQuery } from "@tanstack/react-query";+import PluginsService, { type LocalPlugin } from "#/api/plugins-service";+import { PLUGINS_QUERY_KEYS } from "./query-keys";++/**+ * Query hook for the locally-discovered ("ambient") plugins on the local+ * agent-server (e.g. `~/.agents/plugins`). Read-only and local-backend only — a+ * cloud backend yields an empty list. Rendered as the read-only "Local" group on+ * the Plugins page. Mirrors `usePlugins`.+ */+export const useLocalPlugins = () =>+ useQuery<LocalPlugin[]>({+ queryKey: PLUGINS_QUERY_KEYS.local,+ queryFn: () => PluginsService.getLocalPlugins(),+ staleTime: 1000 * 60 * 10, // 10 minutes+ refetchOnWindowFocus: false,+ });diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex da5ec91a06..7c71d34d94 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -30973,6 +30973,23 @@"tr": "Mevcut","uk": "Доступні"},+ "SETTINGS$PLUGINS_FILTER_LOCAL": {+ "en": "Local",+ "ja": "ローカル",+ "zh-CN": "本地",+ "zh-TW": "本機",+ "ko-KR": "로컬",+ "no": "Lokal",+ "ar": "محلي",+ "de": "Lokal",+ "fr": "Local",+ "it": "Locale",+ "pt": "Local",+ "es": "Local",+ "ca": "Local",+ "tr": "Yerel",+ "uk": "Локальний"+ },"SETTINGS$PLUGINS_REF_LABEL": {"en": "Ref","ja": "リファレンス",diff --git a/src/routes/skills-plugins.tsx b/src/routes/skills-plugins.tsxindex 5f5a950f75..dd44ef6b65 100644--- a/src/routes/skills-plugins.tsx+++ b/src/routes/skills-plugins.tsx@@ -15,6 +15,7 @@ import {} from "#/components/features/plugins/build-plugins-view-model";import { usePluginsMarketplace } from "#/hooks/query/use-plugins-marketplace";import { usePlugins } from "#/hooks/query/use-plugins";+import { useLocalPlugins } from "#/hooks/query/use-local-plugins";import { useInstallPlugin } from "#/hooks/mutation/use-install-plugin";import { useSetPluginEnabled } from "#/hooks/mutation/use-set-plugin-enabled";import { useUninstallPlugin } from "#/hooks/mutation/use-uninstall-plugin";@@ -37,6 +38,7 @@ export default function SkillsPluginsScreen() {const { data: marketplace, isLoading: marketplaceLoading } =usePluginsMarketplace();const { data: installed, isLoading: installedLoading } = usePlugins();+ const { data: local, isLoading: localLoading } = useLocalPlugins();const installPlugin = useInstallPlugin();const setPluginEnabled = useSetPluginEnabled();@@ -50,8 +52,8 @@ export default function SkillsPluginsScreen() {const [showAddModal, setShowAddModal] = React.useState(false);const plugins = React.useMemo(- () => buildPluginsViewModel(marketplace, installed),- [marketplace, installed],+ () => buildPluginsViewModel(marketplace, installed, local),+ [marketplace, installed, local],);const filteredPlugins = React.useMemo(@@ -68,7 +70,7 @@ export default function SkillsPluginsScreen() {? (plugins.find((plugin) => plugin.name === selectedName) ?? null): null;- const isLoading = marketplaceLoading || installedLoading;+ const isLoading = marketplaceLoading || installedLoading || localLoading;const pendingName =(setPluginEnabled.isPending