Skip to content

Agent Zero AI framework

refactor: normalize plugin paths, add README viewer to plugin info modal, and update plugin hub filters

frdelfd3b5253c761
diff --git a/helpers/plugins.py b/helpers/plugins.py
index 87f296f2b..eb503a54c 100644
--- a/helpers/plugins.py
+++ b/helpers/plugins.py
@@ -269,7 +269,7 @@ def get_enhanced_plugins_list(
results.append(
PluginListItem(
name=d.name,
- path=str(d),
+ path=files.normalize_a0_path(str(d)),
display_name=meta.title or d.name,
description=meta.description,
version=meta.version,
diff --git a/plugins/_chat_branching/README.md b/plugins/_chat_branching/README.md
new file mode 100644
index 000000000..f7fcf5204
--- /dev/null
+++ b/plugins/_chat_branching/README.md
@@ -0,0 +1,32 @@
+# Chat Branching
+
+Create a new chat from any existing point in a conversation.
+
+## What It Does
+
+This plugin adds an API endpoint that clones an existing chat context, trims its log history up to a selected message, gives the new chat a `(branch)` suffix, persists it immediately, and refreshes connected tabs so the new branch appears in the UI.
+
+## Main Behavior
+
+- **Clone context**
+ - Serializes the current chat context and deserializes it into a brand-new context with a new ID.
+- **Trim history**
+ - Keeps log entries only up to and including the selected `log_no`.
+ - Includes a fallback for cases where reloaded logs use sequential array indexes.
+- **Persist immediately**
+ - Saves the newly created branched chat to temporary chat storage.
+- **Refresh UI state**
+ - Marks state dirty for all tabs after the branch is created.
+
+## Entry Points
+
+- **API**
+ - `api/branch_chat.py` implements the branching operation.
+- **Extensions**
+ - `extensions/` contains integration glue for making the feature available in the app.
+
+## Plugin Metadata
+
+- **Name**: `_chat_branching`
+- **Title**: `Chat Branching`
+- **Description**: Branch a chat from any message, creating a new chat with history up to that point.
diff --git a/plugins/_code_execution/README.md b/plugins/_code_execution/README.md
new file mode 100644
index 000000000..ff220d29a
--- /dev/null
+++ b/plugins/_code_execution/README.md
@@ -0,0 +1,52 @@
+# Code Execution
+
+Run terminal commands and execute Python or Node.js code through Agent Zero using persistent shell sessions.
+
+## What It Does
+
+This plugin provides the code execution tool used by agents for development tasks. It supports:
+
+- **Terminal commands** in interactive shell sessions
+- **Python execution** through `ipython -c`
+- **Node.js execution** through `node /exe/node_eval.js`
+- **Persistent sessions** keyed by session number
+- **Session reset and output retrieval**
+- **Local or SSH-backed execution** depending on plugin configuration
+
+## Main Behavior
+
+- **Persistent shells**
+ - Maintains per-session shell state in agent data so subsequent calls can reuse the same terminal session.
+- **Multiple runtimes**
+ - Dispatches requests based on `runtime`: `terminal`, `python`, `nodejs`, `output`, or `reset`.
+- **Remote execution support**
+ - Can open SSH interactive sessions instead of local shells when configured.
+- **Streaming output**
+ - Continuously reads shell output, updates the current log item, and detects progress while commands are running.
+- **Safety around running sessions**
+ - Tracks whether a shell is currently busy and can prevent overlapping commands unless explicitly allowed.
+
+## Key Files
+
+- **Tool**
+ - `tools/code_execution_tool.py` contains runtime dispatch, session lifecycle, and streaming output logic.
+- **Helpers**
+ - `helpers/shell_local.py` provides the local interactive shell implementation.
+ - `helpers/shell_ssh.py` provides the SSH-backed interactive shell implementation.
+- **Configuration**
+ - `default_config.yaml` defines execution, prompt, and timeout settings.
+- **Prompts**
+ - `prompts/` contains the response templates shown to the agent.
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+- **Always enabled**: `false`
+
+## Plugin Metadata
+
+- **Name**: `_code_execution`
+- **Title**: `Code Execution`
+- **Description**: Code execution tool supporting terminal, Python, and Node.js runtimes via local TTY or SSH.
diff --git a/plugins/_email_integration/README.md b/plugins/_email_integration/README.md
new file mode 100644
index 000000000..a35f70b04
--- /dev/null
+++ b/plugins/_email_integration/README.md
@@ -0,0 +1,52 @@
+# Email Integration
+
+Communicate with Agent Zero through email inboxes and send replies back over SMTP.
+
+## What It Does
+
+This plugin polls configured mailboxes, downloads incoming messages and attachments, decides whether a message should continue an existing chat or start a new one, and sends replies back by email.
+
+It supports both:
+
+- **IMAP inbox polling**
+- **Exchange inbox polling**
+- **SMTP replies**
+
+## Main Behavior
+
+- **Mailbox polling**
+ - Tracks per-handler mailbox state in `usr/email/state.json`.
+ - Uses UID tracking for IMAP accounts so only new mail is processed after initialization.
+- **Attachment handling**
+ - Downloads attachments into `usr/email/attachments`.
+- **Dispatcher workflow**
+ - Reuses or creates a background `Email Dispatcher` context.
+ - Uses model prompts to decide whether an email belongs to an existing chat or should open a new one.
+- **Thread routing**
+ - Can continue an existing chat by thread ID found in the email subject.
+ - Falls back to model-based dispatch if no direct thread match is available.
+- **Notifications and persistence**
+ - Saves chats after routing and emits notifications about new or continued conversations.
+
+## Key Files
+
+- **Core orchestration**
+ - `helpers/handler.py` manages polling, state persistence, dispatching, and reply flow.
+- **Mail helpers**
+ - `helpers/imap_client.py` handles IMAP and Exchange fetching.
+ - `helpers/smtp_client.py` handles outbound replies.
+ - `helpers/dispatcher.py` formats chat summaries and parses dispatcher decisions.
+- **API and extensions**
+ - `api/` and `extensions/` connect the polling loop and UI-facing operations into the main app.
+
+## Configuration Scope
+
+- **Settings section**: `external`
+- **Per-project config**: `false`
+- **Per-agent config**: `false`
+
+## Plugin Metadata
+
+- **Name**: `_email_integration`
+- **Title**: `Email Integration`
+- **Description**: Communicate with Agent Zero via email. Supports IMAP/Exchange inbox polling with SMTP replies.
diff --git a/plugins/_error_retry/README.md b/plugins/_error_retry/README.md
new file mode 100644
index 000000000..a37a371d2
--- /dev/null
+++ b/plugins/_error_retry/README.md
@@ -0,0 +1,39 @@
+# Error Retry
+
+Retry once after an unexpected critical exception so the agent has a chance to recover instead of failing immediately.
+
+## What It Does
+
+This plugin hooks into the agent lifecycle and automatically retries the current loop once when an unhandled critical exception occurs.
+
+It does **not** retry exceptions that are already treated as controlled agent flow, such as:
+
+- `HandledException`
+- `RepairableException`
+
+## Main Behavior
+
+- **Counter reset per monologue**
+ - Clears the retry counter at the start of a new monologue.
+- **Critical exception retry**
+ - On an unexpected exception, logs a warning, waits briefly, injects an agent-facing critical error message into history, and suppresses the original exception once.
+- **Single retry only**
+ - Uses an internal counter so the retry happens at most one time per monologue.
+
+## Key Files
+
+- `extensions/python/agent_Agent_monologue_start/_10_reset_critical_exception_counter.py`
+- `extensions/python/agent_Agent_handle_exception_end/_80_retry_critical_exception.py`
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+- **Always enabled**: `false`
+
+## Plugin Metadata
+
+- **Name**: `_error_retry`
+- **Title**: `Error Retry`
+- **Description**: Retry on critical exceptions before failing.
diff --git a/plugins/_infection_check/README.md b/plugins/_infection_check/README.md
index b89c3ae3b..3c389e6e1 100644
--- a/plugins/_infection_check/README.md
+++ b/plugins/_infection_check/README.md
@@ -1,8 +1,12 @@
# Infection Check
-Safety middleware that scans agent outputs for prompt injection, credential leaks, and malicious behavior before allowing tool execution.
+Safety middleware that analyzes agent output for prompt injection and suspicious external influence before allowing tool execution.
-## How it Works
+## What It Does
+
+This plugin collects streamed reasoning and response text, analyzes that content with a configurable audit model, and blocks tool execution until the safety check either passes, requests clarification, or terminates the agent.
+
+## How It Works
1. **Collection** — During streaming, the plugin collects the agent's reasoning and response text via `reasoning_stream_chunk` and `response_stream_chunk` extensions.
2. **Analysis** — A security audit model analyzes the collected text against the configurable prompt.
@@ -49,6 +53,17 @@ When the check results in `<terminate/>` (directly or after exhausting clarifica
| History Size | `10` | Recent messages included as context |
| Prompt | *(built-in)* | Fully customizable security audit system prompt |
+## Key Files
+
+- **Checker logic**
+ - `helpers/checker.py` implements stream collection, background analysis, gating, clarification, and termination.
+- **Extensions**
+ - `extensions/python/reasoning_stream_chunk/_50_infection_collect.py`
+ - `extensions/python/response_stream_chunk/_50_infection_collect.py`
+ - `extensions/python/response_stream/_50_infection_analyze.py`
+ - `extensions/python/response_stream_end/_50_infection_analyze.py`
+ - `extensions/python/tool_execute_before/_50_infection_check.py`
+
## Extension Points Used
| Extension Point | File | Purpose |
@@ -58,3 +73,15 @@ When the check results in `<terminate/>` (directly or after exhausting clarifica
| `response_stream` | `_50_infection_analyze.py` | Detect thoughts complete → start background analysis |
| `response_stream_end` | `_50_infection_analyze.py` | Start analysis (complete mode / fallback) |
| `tool_execute_before` | `_50_infection_check.py` | Await check result → gate tool execution |
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+
+## Plugin Metadata
+
+- **Name**: `_infection_check`
+- **Title**: `Infection Check`
+- **Description**: Safety check for prompt injection from external sources.
diff --git a/plugins/_memory/README.md b/plugins/_memory/README.md
new file mode 100644
index 000000000..9b6d9617c
--- /dev/null
+++ b/plugins/_memory/README.md
@@ -0,0 +1,51 @@
+# Memory
+
+Provide persistent vector-based memory and knowledge retrieval for Agent Zero.
+
+## What It Does
+
+This plugin stores memories and knowledge embeddings in a FAISS-backed vector database, exposes tools for saving and recalling memories, and provides APIs and UI support for browsing, importing, updating, and deleting memory entries.
+
+## Main Behavior
+
+- **Persistent vector store**
+ - Creates and loads FAISS indexes per memory subdirectory.
+ - Stores embedding metadata so the index can be rebuilt if the embedding model changes.
+- **Knowledge preloading**
+ - Loads configured knowledge directories into memory when a database is initialized.
+- **Memory tools**
+ - Includes tools for saving, loading, deleting, forgetting, and behavior adjustment workflows.
+- **Dashboard APIs**
+ - Exposes search, delete, bulk delete, update, and subdirectory listing endpoints for the memory dashboard.
+- **Scoped storage**
+ - Supports different memory subdirectories so memory can be separated by context or agent scope.
+
+## Key Files
+
+- **Core memory engine**
+ - `helpers/memory.py` implements FAISS storage, index loading, embedding configuration, and knowledge preload.
+- **Knowledge import**
+ - `helpers/knowledge_import.py` imports external knowledge into memory storage.
+- **Consolidation**
+ - `helpers/memory_consolidation.py` contains memory consolidation logic.
+- **Tools**
+ - `tools/memory_save.py`
+ - `tools/memory_load.py`
+ - `tools/memory_delete.py`
+ - `tools/memory_forget.py`
+ - `tools/behaviour_adjustment.py`
+- **API**
+ - `api/memory_dashboard.py` powers the memory management dashboard.
+ - `api/import_knowledge.py` and `api/knowledge_reindex.py` handle knowledge import and reindexing.
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+
+## Plugin Metadata
+
+- **Name**: `_memory`
+- **Title**: `Memory`
+- **Description**: Provides persistent memory capabilities to Agent Zero agents.
diff --git a/plugins/_model_config/README.md b/plugins/_model_config/README.md
new file mode 100644
index 000000000..ff218d46d
--- /dev/null
+++ b/plugins/_model_config/README.md
@@ -0,0 +1,53 @@
+# Model Configuration
+
+Manage which models Agent Zero uses for chat, utility, and embeddings, with support for scoped overrides and reusable presets.
+
+## What It Does
+
+This plugin centralizes model selection and model-related settings for the application. It provides helpers and APIs for:
+
+- selecting chat, utility, and embedding models
+- reading and saving model presets
+- checking for missing API keys
+- allowing optional per-chat model overrides
+- resolving config at global, project, agent, and chat scope
+
+## Main Behavior
+
+- **Scoped configuration**
+ - Reads plugin config through the standard plugin config system with project and agent overrides.
+- **Preset management**
+ - Loads presets from a user file when present and falls back to bundled defaults.
+- **Per-chat override**
+ - Allows a chat context to store a temporary override or preset reference in context data.
+- **Model object construction**
+ - Builds `ModelConfig` objects and the runtime chat, browser, utility, and embedding wrappers used elsewhere in the app.
+- **API key validation**
+ - Reports configured providers that still require API keys.
+
+## Key Files
+
+- **Core helper**
+ - `helpers/model_config.py` resolves config, presets, overrides, and runtime model objects.
+- **APIs**
+ - `api/model_config_get.py`
+ - `api/model_config_set.py`
+ - `api/model_override.py`
+ - `api/model_presets.py`
+ - `api/model_search.py`
+ - `api/api_keys.py`
+- **Hooks**
+ - `hooks.py` exposes plugin-level integration hooks.
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+- **Always enabled**: `true`
+
+## Plugin Metadata
+
+- **Name**: `_model_config`
+- **Title**: `Model Configuration`
+- **Description**: Manages LLM model selection and configuration for chat, utility, and embedding models. Supports per-project and per-agent overrides with optional per-chat model switching.
diff --git a/plugins/_plugin_installer/README.md b/plugins/_plugin_installer/README.md
new file mode 100644
index 000000000..07c34213d
--- /dev/null
+++ b/plugins/_plugin_installer/README.md
@@ -0,0 +1,44 @@
+# Plugin Installer
+
+Install and update Agent Zero plugins from ZIP uploads, Git repositories, or a community index.
+
+## What It Does
+
+This plugin provides the built-in installation workflow for third-party plugins. It validates plugin manifests, prevents naming conflicts, installs plugins into `usr/plugins/`, optionally updates Git-based plugins, and exposes a UI for browsing and installing community plugins.
+
+## Main Behavior
+
+- **ZIP install**
+ - Accepts an uploaded archive, extracts it safely, locates `plugin.yaml`, validates metadata, and moves the plugin into `usr/plugins/`.
+- **Git install**
+ - Clones a repository to a temporary directory, validates the plugin, then installs it into `usr/plugins/`.
+- **Plugin update**
+ - Updates already installed Git-backed custom plugins and re-runs installation hooks.
+- **Safety checks**
+ - Rejects archives with unsafe paths.
+ - Rejects missing or invalid `plugin.yaml` files.
+ - Rejects plugin name conflicts.
+- **Install hooks and refresh**
+ - Runs the plugin install hook when present and calls `after_plugin_change(...)` so the app refreshes plugin state.
+- **Community browsing UI**
+ - The web UI store handles browsing index entries, showing readme content, prompting about third-party plugin risk, and launching install/update actions.
+
+## Key Files
+
+- **API**
+ - `api/plugin_install.py` dispatches install, update, and index fetch actions.
+- **Installer logic**
+ - `helpers/install.py` contains archive extraction, Git install, update, validation, and hook execution.
+- **Frontend**
+ - `webui/pluginInstallStore.js` manages the installer modal state and community index interactions.
+
+## Configuration Scope
+
+- **Settings sections**: none
+- **Always enabled**: `true`
+
+## Plugin Metadata
+
+- **Name**: `_plugin_installer`
+- **Title**: `Plugin Installer`
+- **Description**: Install plugins from ZIP files, Git repositories, or the community index.
diff --git a/plugins/_plugin_installer/webui/pluginInstallStore.js b/plugins/_plugin_installer/webui/pluginInstallStore.js
index cbe9249e7..d6fd0340d 100644
--- a/plugins/_plugin_installer/webui/pluginInstallStore.js
+++ b/plugins/_plugin_installer/webui/pluginInstallStore.js
@@ -11,7 +11,7 @@ import { store as pluginExecuteStore } from "/components/plugins/list/plugin-exe
import { store as pluginSettingsStore } from "/components/plugins/plugin-settings-store.js";
const PLUGIN_API = "plugins/_plugin_installer/plugin_install";
-const PER_PAGE = 20;
+const PER_PAGE = 24;
const SECURITY_WARNING = {
title: "Security Warning",
@@ -143,7 +143,7 @@ const model = {
if (!filterKey || filterKey === "all") return true;
if (filterKey === "installed") return !!plugin?.installed;
if (filterKey === "update") return !!plugin?.has_update;
- if (filterKey === "popular") return (plugin?.stars || 0) > 0;
+ if (filterKey === "popular") return (plugin?.stars || 0) >= 3;
if (filterKey.startsWith("tag:")) {
return this._pluginPrimaryTag(plugin) === filterKey.slice(4);
}
diff --git a/plugins/_plugin_scan/README.md b/plugins/_plugin_scan/README.md
new file mode 100644
index 000000000..e11fa68ae
--- /dev/null
+++ b/plugins/_plugin_scan/README.md
@@ -0,0 +1,40 @@
+# Plugin Scanner
+
+Run an LLM-guided security review of third-party Agent Zero plugins from a Git repository.
+
+## What It Does
+
+This plugin builds a structured scanning prompt from a selectable checklist, runs that prompt in a temporary agent context, and returns a markdown report describing the plugin's security posture.
+
+## Main Behavior
+
+- **Prompt-driven scan**
+ - Loads scan checks and a markdown prompt template from the plugin's `webui/` assets.
+- **Temporary scan context**
+ - Creates a temporary chat context, sends the generated prompt as a user message, waits for the model result, and then removes the chat.
+- **Selectable checks**
+ - Supports scanning all checks by default or only the subset selected by the caller.
+- **UI integration**
+ - Includes API endpoints and web UI files for queueing, starting, and running scans.
+
+## Key Files
+
+- **Scan runner**
+ - `api/plugin_scan_run.py` performs a synchronous end-to-end scan and returns the report.
+- **Prompt builder**
+ - `helpers/prompt.py` loads check definitions and renders the final scan prompt.
+- **Additional APIs**
+ - `api/plugin_scan_queue.py`
+ - `api/plugin_scan_start.py`
+
+## Configuration Scope
+
+- **Settings sections**: none
+- **Per-project config**: `false`
+- **Per-agent config**: `false`
+
+## Plugin Metadata
+
+- **Name**: `_plugin_scan`
+- **Title**: `Plugin Scanner`
+- **Description**: Security scanner for third-party A0 plugins.
diff --git a/plugins/_plugin_validator/README.md b/plugins/_plugin_validator/README.md
new file mode 100644
index 000000000..fca75202e
--- /dev/null
+++ b/plugins/_plugin_validator/README.md
@@ -0,0 +1,41 @@
+# Plugin Validator
+
+Validate Agent Zero plugins against structural, manifest, convention, and security expectations.
+
+## What It Does
+
+This plugin generates a structured validation prompt for either a local plugin or an external source, runs the review in a temporary agent context, and returns a markdown report that checks whether a plugin follows Agent Zero plugin conventions.
+
+## Main Behavior
+
+- **Source-aware validation**
+ - Supports validating a local plugin by name or a plugin fetched from a Git repository.
+- **Checklist-based review**
+ - Loads validation criteria, status icons, and guidance text from plugin assets.
+- **Temporary validation context**
+ - Creates a temporary agent context, runs the generated prompt, and cleans up the context and temporary chat afterward.
+- **Operational guidance in prompt**
+ - Embeds source-specific handling instructions into the prompt, including cleanup rules for temporary validation directories.
+
+## Key Files
+
+- **Validation runner**
+ - `api/plugin_validator_run.py` performs a synchronous validation and returns the report.
+- **Prompt builder**
+ - `helpers/prompt.py` builds the validation prompt with source instructions, selected checks, and scoring guidance.
+- **Additional APIs**
+ - `api/plugin_validator_prepare_zip.py`
+ - `api/plugin_validator_queue.py`
+ - `api/plugin_validator_start.py`
+
+## Configuration Scope
+
+- **Settings sections**: none
+- **Per-project config**: `false`
+- **Per-agent config**: `false`
+
+## Plugin Metadata
+
+- **Name**: `_plugin_validator`
+- **Title**: `Plugin Validator`
+- **Description**: Validate Agent Zero plugins against manifest, structure, code pattern, and security conventions.
diff --git a/plugins/_promptinclude/README.md b/plugins/_promptinclude/README.md
new file mode 100644
index 000000000..fa23204eb
--- /dev/null
+++ b/plugins/_promptinclude/README.md
@@ -0,0 +1,40 @@
+# Prompt Include
+
+Automatically inject persistent behavioral rules and preferences into the system prompt from project files.
+
+## What It Does
+
+This plugin scans a workspace for `*.promptinclude.md` files, applies gitignore-aware filtering and token budgets, and makes the collected content available for prompt injection.
+
+## Main Behavior
+
+- **Workspace scanning**
+ - Recursively searches for files matching `*.promptinclude.md`.
+- **Ignore support**
+ - Respects ignore patterns derived from gitignore-style content.
+- **Budgeted inclusion**
+ - Applies per-file and total token limits.
+ - Crops oversized files when they partially fit within the remaining token budget.
+- **Structured scan result**
+ - Returns included file content together with path, token count, status, and skipped count.
+
+## Key Files
+
+- **Scanner**
+ - `helpers/scanner.py` implements file discovery, ignore handling, token budgeting, and trimming.
+- **Configuration**
+ - `default_config.yaml` contains prompt-include scanning defaults.
+- **Prompts and UI**
+ - `prompts/` and `webui/` provide integration with the broader app.
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+
+## Plugin Metadata
+
+- **Name**: `_promptinclude`
+- **Title**: `Prompt Include`
+- **Description**: Persistent behavioral rules and preferences auto-injected into system prompt.
diff --git a/plugins/_text_editor/README.md b/plugins/_text_editor/README.md
new file mode 100644
index 000000000..e0547df97
--- /dev/null
+++ b/plugins/_text_editor/README.md
@@ -0,0 +1,44 @@
+# Text Editor
+
+Provide an LLM-friendly file editing tool for reading, writing, and patching text files.
+
+## What It Does
+
+This plugin exposes a native text editing tool that agents can use to inspect files, write complete contents, and apply validated patch operations while tracking file freshness between reads and edits.
+
+## Main Behavior
+
+- **Read**
+ - Reads whole files or line ranges with token-aware limits.
+ - Records file metadata so later patch operations can detect stale edits.
+- **Write**
+ - Writes full file contents and then re-reads the resulting file for confirmation.
+- **Patch**
+ - Validates edit structures before applying them.
+ - Rejects edits if the file changed since it was last observed.
+ - Reads back the affected patch region after applying changes.
+- **Extension hooks**
+ - Exposes before and after extension points for read, write, and patch operations.
+
+## Key Files
+
+- **Tool**
+ - `tools/text_editor.py` implements method dispatch, stale-file checks, patching flow, and prompt responses.
+- **Helpers**
+ - `helpers/file_ops.py` provides file info, read/write helpers, edit validation, and patch application.
+- **Configuration**
+ - `default_config.yaml` defines read limits and token budgets.
+- **Prompts**
+ - `prompts/` contains the agent-facing success and error messages.
+
+## Configuration Scope
+
+- **Settings section**: `agent`
+- **Per-project config**: `true`
+- **Per-agent config**: `true`
+
+## Plugin Metadata
+
+- **Name**: `_text_editor`
+- **Title**: `Text Editor`
+- **Description**: Native tool to read, write, and patch text files in an LLM-friendly way.
diff --git a/webui/components/plugins/list/pluginListStore.js b/webui/components/plugins/list/pluginListStore.js
index 25aff0767..e6d9809ef 100644
--- a/webui/components/plugins/list/pluginListStore.js
+++ b/webui/components/plugins/list/pluginListStore.js
@@ -1,5 +1,7 @@
import { createStore } from "/js/AlpineStore.js";
import * as api from "/js/api.js";
+import { marked } from "/vendor/marked/marked.esm.js";
+import { addBlankTargetsToLinks } from "/js/messages.js";
import { store as pluginSettingsStore } from "/components/plugins/plugin-settings-store.js";
import { store as pluginToggleStore } from "/components/plugins/toggle/plugin-toggle-store.js";
import { store as pluginExecuteStore } from "/components/plugins/list/plugin-execute-store.js";
@@ -17,6 +19,9 @@ const model = {
plugins: [],
selectedPlugin: null,
activeTab: "custom",
+ readmeContent: "",
+ readmeLoading: false,
+ readmeError: "",
async init() {
this.loading = false;
@@ -151,9 +156,36 @@ const model = {
}
},
+ async loadPluginReadme(plugin) {
+ this.readmeLoading = true;
+ this.readmeContent = "";
+ this.readmeError = "";
+ try {
+ const response = await api.callJsonApi("plugins", {
+ action: "get_doc",
+ plugin_name: plugin.name,
+ doc: "readme",
+ });
+ if (response?.error) throw new Error(response.error);
+ const html = marked.parse(response.content || "", { breaks: true });
+ this.readmeContent = addBlankTargetsToLinks(html);
+ } catch (e) {
+ const error = e instanceof Error ? e : new Error(String(e));
+ this.readmeError = error.message || "Failed to load README";
+ } finally {
+ this.readmeLoading = false;
+ }
+ },
+
openPluginInfo(plugin) {
if (!plugin) return;
this.selectedPlugin = plugin;
+ this.readmeContent = "";
+ this.readmeLoading = false;
+ this.readmeError = "";
+ if (plugin.has_readme) {
+ void this.loadPluginReadme(plugin);
+ }
window.openModal?.("components/plugins/plugin-info.html");
},
diff --git a/webui/components/plugins/plugin-info.html b/webui/components/plugins/plugin-info.html
index d3f8477b4..428f3a0fb 100644
--- a/webui/components/plugins/plugin-info.html
+++ b/webui/components/plugins/plugin-info.html
@@ -73,6 +73,32 @@
<div class="plugin-info-value"
x-text="$store.pluginListStore.selectedPlugin.has_config_screen ? 'Available' : 'Not available'"></div>
</div>
+
+ <div class="plugin-info-readme-section"
+ x-show="$store.pluginListStore.selectedPlugin.has_readme || $store.pluginListStore.readmeLoading || $store.pluginListStore.readmeError || $store.pluginListStore.readmeContent">
+ <button type="button"
+ class="plugin-info-readme-toggle"
+ data-bs-toggle="collapse"
+ data-bs-target="#plugin-info-readme-collapse"
+ aria-expanded="false"
+ aria-controls="plugin-info-readme-collapse">
+ <span>README</span>
+ <span class="material-symbols-outlined plugin-info-readme-toggle-icon">expand_more</span>
+ </button>
+ <div class="collapse" id="plugin-info-readme-collapse">
+ <div class="plugin-info-readme-body">
+ <div x-show="$store.pluginListStore.readmeLoading" class="plugin-info-loading-text">
+ Loading readme...
+ </div>
+ <div x-show="$store.pluginListStore.readmeError && !$store.pluginListStore.readmeLoading"
+ class="plugin-info-readme-error"
+ x-text="$store.pluginListStore.readmeError"></div>
+ <div x-show="$store.pluginListStore.readmeContent && !$store.pluginListStore.readmeLoading"
+ class="plugin-info-readme-content"
+ x-html="$store.pluginListStore.readmeContent"></div>
+ </div>
+ </div>
+ </div>
</div>
</template>
@@ -170,6 +196,146 @@
gap: 0.5rem 0.75rem;
}
+ .plugin-info-readme-section {
+ margin-top: 1.5rem;
+ padding-top: 1rem;
+ border-top: 1px solid var(--color-border);
+ }
+
+ .plugin-info-readme-toggle {
+ width: 100%;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.75rem;
+ padding: 0;
+ border: 0;
+ background: transparent;
+ color: var(--color-text-primary);
+ font-size: 0.95rem;
+ font-weight: 600;
+ text-align: left;
+ cursor: pointer;
+ }
+
+ .plugin-info-readme-toggle-icon {
+ transition: transform 0.2s ease;
+ }
+
+ .plugin-info-readme-toggle[aria-expanded="true"] .plugin-info-readme-toggle-icon {
+ transform: rotate(180deg);
+ }
+
+ .plugin-info-readme-body {
+ padding-top: 0.85rem;
+ }
+
+ .plugin-info-loading-text,
+ .plugin-info-readme-error {
+ color: var(--color-text-secondary);
+ }
+
+ .plugin-info-readme-content {
+ font-size: 0.95rem;
+ line-height: 1.6;
+ color: var(--color-text-primary);
+ overflow-x: auto;
+ scrollbar-width: none;
+ -ms-overflow-style: none;
+ }
+
+ .plugin-info-readme-content::-webkit-scrollbar {
+ display: none;
+ }
+
+ .plugin-info-readme-content h1,
+ .plugin-info-readme-content h2,
+ .plugin-info-readme-content h3,
+ .plugin-info-readme-content h4 {
+ margin-top: 1rem;
+ margin-bottom: 0.5rem;
+ color: var(--color-text-primary);
+ }
+
+ .plugin-info-readme-content h1 { font-size: 1.5rem; }
+ .plugin-info-readme-content h2 { font-size: 1.25rem; }
+ .plugin-info-readme-content h3 { font-size: 1.1rem; }
+ .plugin-info-readme-content h4 { font-size: 1rem; }
+
+ .plugin-info-readme-content p {
+ margin-bottom: 0.75rem;
+ }
+
+ .plugin-info-readme-content code {
+ background: var(--color-panel);
+ padding: 0.15rem 0.35rem;
+ border-radius: 4px;
+ font-family: var(--font-family-mono);
+ font-size: 0.85em;
+ }
+
+ .plugin-info-readme-content pre {
+ background: var(--color-panel);
+ padding: 1rem;
+ border-radius: 8px;
+ overflow-x: auto;
+ margin-bottom: 1rem;
+ }
+
+ .plugin-info-readme-content pre code {
+ background: none;
+ padding: 0;
+ }
+
+ .plugin-info-readme-content ul,
+ .plugin-info-readme-content ol {
+ margin-bottom: 0.75rem;
+ padding-left: 1.5rem;
+ }
+
+ .plugin-info-readme-content li {
+ margin-bottom: 0.25rem;
+ }
+
+ .plugin-info-readme-content a {
+ color: var(--color-highlight);
+ text-decoration: none;
+ }
+
+ .plugin-info-readme-content a:hover {
+ text-decoration: underline;
+ }
+
+ .plugin-info-readme-content img {
+ max-width: 100%;
+ border-radius: 8px;
+ margin: 0.5rem 0;
+ }
+
+ .plugin-info-readme-content blockquote {
+ border-left: 3px solid var(--color-border);
+ padding-left: 1rem;
+ margin-left: 0;
+ color: var(--color-text-secondary);
+ }
+
+ .plugin-info-readme-content table {
+ width: 100%;
+ border-collapse: collapse;
+ margin-bottom: 1rem;
+ }
+
+ .plugin-info-readme-content th,
+ .plugin-info-readme-content td {
+ border: 1px solid var(--color-border);
+ padding: 0.5rem;
+ text-align: left;
+ }
+
+ .plugin-info-readme-content th {
+ background: var(--color-panel);
+ }
+
.plugin-info-grid-pair {
display: contents;
}