Skip to content

🙌 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.ts
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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>
) : (
<BrandButton
type="button"
@@ -111,7 +118,7 @@ export function PluginCard({
</p>
) : null}
- {plugin.installed && plugin.version ? (
+ {(plugin.installed || plugin.isLocal) && plugin.version ? (
<span
data-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.tsx
index 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 : (
<BrandButton
type="button"
variant="primary"
diff --git a/src/components/features/plugins/plugins-toolbar.tsx b/src/components/features/plugins/plugins-toolbar.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.json
index 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.tsx
index 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