@elizaos/plugin-registry 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @elizaos/plugin-registry
+
+Plugin discovery, manifest reading, install/uninstall lifecycle, and HTTP route handlers for plugin management in elizaOS.
+
+## What it does
+
+`@elizaos/plugin-registry` consolidates the plugin-management HTTP API that was previously split across `@elizaos/agent` and `@elizaos/app-core`. It provides:
+
+- **Plugin list API** — merges bundled plugins (from the static registry), runtime-loaded plugins, and store-installed plugins into a single list with enabled/active status, validation errors, and registry metadata (version, release stream, icon, links).
+- **Plugin toggle and config** — `PUT /api/plugins/:id` enables/disables a plugin and writes config env vars; changes are applied to the live runtime when possible, or a restart is scheduled.
+- **Install / update / uninstall** — `POST /api/plugins/install|update|uninstall` download or remove plugins from the npm registry, update `eliza.json`, and attempt a live runtime reload.
+- **Advanced lifecycle operations** — eject a plugin to a local source checkout (`/eject`), sync it with upstream (`/sync`), or restore it to the registry version (`/reinject`).
+- **Secrets surface** — `GET /api/secrets` aggregates all sensitive plugin parameters across the full plugin list; `PUT /api/secrets` bulk-writes secrets to `process.env`.
+- **Plugin health probes** — `POST /api/plugins/:id/test` calls a plugin's `health`/`testConnection` method or performs a live connectivity check (e.g. Telegram bot token validation).
+- **Core plugin management** — `GET /api/plugins/core` and `POST /api/plugins/core/toggle` manage optional core plugins via the `plugins.allow` list in `eliza.json`.
+- **Drift diagnostics** — `GET /api/plugins/diagnostics` detects mismatches between the Settings UI model and the raw config.
+
+## Exported API
+
+```ts
+import {
+  // Agent-tier route handler
+  handlePluginRoutes,
+
+  // App-core compat-tier route handler + list builder
+  handlePluginsCompatRoutes,
+  buildPluginListResponse,
+
+  // Install lifecycle forwarders (lazy-load; break app-core ↔ agent cycle)
+  installPlugin,
+  installAndRestart,
+  uninstallPlugin,
+  uninstallAndRestart,
+  listInstalledPlugins,
+
+  // Types
+  type InstallPhase,
+  type InstallProgress,
+  type InstallResult,
+  type ProgressCallback,
+  type UninstallResult,
+} from "@elizaos/plugin-registry";
+```
+
+## Route surface
+
+### Agent-tier (`handlePluginRoutes`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/plugins` | Full plugin list |
+| PUT | `/api/plugins/:id` | Toggle enabled / write config |
+| GET | `/api/secrets` | Aggregate sensitive params |
+| PUT | `/api/secrets` | Bulk-write secrets to env |
+| POST | `/api/plugins/:id/test` | Plugin health probe |
+| POST | `/api/plugins/install` | Install from npm registry |
+| POST | `/api/plugins/update` | Update installed plugin |
+| POST | `/api/plugins/uninstall` | Uninstall plugin |
+| POST | `/api/plugins/:id/eject` | Eject to local source |
+| POST | `/api/plugins/:id/sync` | Sync ejected plugin |
+| POST | `/api/plugins/:id/reinject` | Restore to registry version |
+| GET | `/api/plugins/installed` | List runtime-installed plugins |
+| GET | `/api/plugins/ejected` | List ejected plugins |
+| GET | `/api/core/status` | `@elizaos/core` eject status |
+| GET | `/api/plugins/core` | Core + optional-core list |
+| POST | `/api/plugins/core/toggle` | Toggle optional-core plugin |
+
+### App-core compat-tier (`handlePluginsCompatRoutes`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/plugins` | Plugin list (registry + manifest + runtime) |
+| GET | `/api/plugins/diagnostics` | Drift diagnostics |
+| PUT | `/api/plugins/:id` | Toggle / config + vault mirror |
+| POST | `/api/plugins/:id/test` | Connectivity test |
+| POST | `/api/plugins/:id/reveal` | Reveal raw env value from vault |
+
+## Required config / env
+
+This package reads no env vars of its own. Plugin-specific env vars (e.g. `OPENAI_API_KEY`, `TELEGRAM_BOT_TOKEN`) are declared by each plugin's `pluginParameters` manifest entry and are read from `process.env` when building the plugin list or handling config writes.
+
+The optional `ELIZA_SETTINGS_DEBUG` env var enables verbose before/after logging on PUT operations.
+
+## Dependencies
+
+- `@elizaos/core` — `AgentRuntime`, `logger`
+- `@elizaos/shared` — shared request/response schemas, plugin constants
+- `@elizaos/vault` — encrypted secret storage (via `@elizaos/app-core` vault-mirror service)
+
+The canonical plugin install implementation lives in `@elizaos/agent`. The forwarders in `src/services/plugin-installer.ts` lazy-load it at call time to avoid a static circular dependency.

package/dist/api/app-plugins-routes.d.ts

@@ -0,0 +1,103 @@
+import type http from "node:http";
+import { loadElizaConfig } from "@elizaos/agent";
+import { type CompatRuntimeState } from "@elizaos/app-core/api/compat-route-shared";
+import { _resetSharedVaultForTesting, mirrorPluginSensitiveToVault } from "@elizaos/app-core/services/vault-mirror";
+import { type AgentRuntime } from "@elizaos/core";
+type PluginCategory = "ai-provider" | "connector" | "streaming" | "database" | "app" | "feature";
+interface CompatPluginParameter {
+    key: string;
+    type: string;
+    description: string;
+    required: boolean;
+    sensitive: boolean;
+    default?: string;
+    options?: string[];
+    currentValue: string | null;
+    isSet: boolean;
+}
+interface CompatPluginRecord {
+    id: string;
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    configured?: boolean;
+    envKey?: string | null;
+    category?: PluginCategory;
+    source?: string;
+    parameters: CompatPluginParameter[];
+    validationErrors: Array<{
+        field: string;
+        message: string;
+    }>;
+    validationWarnings?: Array<{
+        field?: string;
+        message: string;
+    }>;
+    npmName?: string;
+    version?: string;
+    isActive?: boolean;
+    tags?: string[];
+    configKeys?: string[];
+    pluginDeps?: string[];
+    configUiHints?: Record<string, unknown>;
+    icon?: string | null;
+    homepage?: string;
+    repository?: string;
+    setupGuideUrl?: string;
+    iconName?: string;
+    group?: string;
+    groupOrder?: number;
+    visible?: boolean;
+}
+type PluginDriftFlag = "entries_vs_compat" | "entries_vs_allowlist" | "inactive_but_enabled" | "active_but_disabled";
+interface PluginDriftDiagnostic {
+    pluginId: string;
+    npmName: string | null;
+    category: PluginCategory;
+    enabled_ui: boolean;
+    enabled_allowlist: boolean | null;
+    is_active: boolean;
+    drift_flags: PluginDriftFlag[];
+}
+interface PluginDriftDiagnosticsSummary {
+    total: number;
+    withDrift: number;
+    byFlag: Record<PluginDriftFlag, number>;
+}
+interface PluginDriftDiagnosticsReport {
+    summary: PluginDriftDiagnosticsSummary;
+    plugins: PluginDriftDiagnostic[];
+}
+export { _resetSharedVaultForTesting, mirrorPluginSensitiveToVault };
+export declare function resolveCompatPluginEnabledForList(active: boolean, persistedEnabled: boolean | undefined, advancedCapabilityEnabled?: boolean): boolean;
+export declare function analyzePluginStateDrift(pluginList: CompatPluginRecord[], configRecord: Record<string, unknown>, configEntries: Record<string, {
+    enabled?: unknown;
+}>, allowList: Set<string> | null): PluginDriftDiagnosticsReport;
+export declare function resolvePluginManifestPath(): string | null;
+export declare function resolveAdvancedCapabilityCompatStatus(pluginId: string, config: ReturnType<typeof loadElizaConfig>, runtime: Pick<AgentRuntime, "getService"> | null): {
+    enabled: boolean;
+    isActive: boolean;
+} | null;
+export declare function buildPluginListResponse(runtime: AgentRuntime | null): {
+    plugins: CompatPluginRecord[];
+};
+export declare function persistCompatPluginMutation(pluginId: string, body: Record<string, unknown>, plugin: CompatPluginRecord): {
+    status: number;
+    payload: Record<string, unknown>;
+};
+/**
+ * Plugin management routes.
+ *
+ * Contract note:
+ * - `/api/plugins` is the Settings/UI model.
+ * - `/api/plugins/core` is the optional-core allow-list model.
+ * - These can drift; use `/api/plugins/diagnostics` to inspect mismatches.
+ *
+ * - `GET  /api/plugins`             — returns filtered plugin list
+ * - `GET  /api/plugins/diagnostics` — returns drift diagnostics
+ * - `PUT  /api/plugins/:id`         — updates plugin config, writes env vars
+ * - `POST /api/plugins/:id/test`    — tests plugin connectivity
+ * - `POST /api/plugins/:id/reveal`  — reveals plugin env var value
+ */
+export declare function handlePluginsCompatRoutes(req: http.IncomingMessage, res: http.ServerResponse, state: CompatRuntimeState): Promise<boolean>;
+//# sourceMappingURL=app-plugins-routes.d.ts.map

package/dist/api/app-plugins-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-plugins-routes.d.ts","sourceRoot":"","sources":["../../src/api/app-plugins-routes.ts"],"names":[],"mappings":"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"}