Agent Zero AI framework
plugins: update docs and skills for extensible refactor
Alessandroc48b26797e6b
diff --git a/docs/agents/AGENTS.plugins.md b/docs/agents/AGENTS.plugins.mdindex a5a1851a4..f94a3e95a 100644--- a/docs/agents/AGENTS.plugins.md+++ b/docs/agents/AGENTS.plugins.md@@ -12,7 +12,7 @@ Agent Zero uses a convention-over-configuration plugin model where runtime capab1. Backend discovery (python/helpers/plugins.py): Resolves roots (usr/plugins/ first, then plugins/) and builds the effective set of plugins.2. Path resolution (python/helpers/subagents.py): Injects plugin paths into the agent's search space for prompts, tools, and configurations.-3. Python extensions (python/helpers/extension.py): Executes lifecycle hooks from extensions/python/<point>/.+3. Python extensions (python/helpers/extension.py): Executes named lifecycle hooks from `extensions/python/<point>/` and implicit `@extensible` hooks from `extensions/python/_functions/<module>/<qualname>/<start|end>/`.4. WebUI extensions (webui/js/extensions.js): Injects HTML/JS contributions into core UI breakpoints (x-extension).---@@ -37,13 +37,23 @@ usr/plugins/<plugin_name>/├── prompts/ # Prompt templates├── agents/ # Agent profiles (agents/<profile>/agent.yaml)├── extensions/-│ ├── python/<point>/ # Backend lifecycle hooks+│ ├── python/<point>/ # Named backend lifecycle hooks+│ ├── python/_functions/<module>/<qualname>/<start|end>/ # Implicit @extensible hooks│ └── webui/<point>/ # UI HTML/JS contributions└── webui/├── config.html # Optional: Plugin settings UI└── ... # Full plugin pages/components```+### Python extension layouts++Use one of these backend extension layouts, depending on what you are extending:++- `extensions/python/<extension_point>/` for named lifecycle hooks such as `system_prompt`, `monologue_start`, or `tool_execute_before`+- `extensions/python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` call sites++The `_functions` layout preserves every module segment and every nested `__qualname__` segment. Do not use the retired flattened form `extensions/python/<module>_<qualname>_<start|end>/`; those folder names no longer match the runtime lookup logic.+### Python import rule for user pluginsFor plugin-local Python code in `usr/plugins/<plugin_name>/`, import through thediff --git a/docs/developer/plugins.md b/docs/developer/plugins.mdindex b16cb5428..60132206f 100644--- a/docs/developer/plugins.md+++ b/docs/developer/plugins.md@@ -6,7 +6,7 @@ This page documents the current Agent Zero plugin system, including manifest forPlugins extend Agent Zero through convention-based folders. A plugin can provide:-- Backend: API handlers, tools, helpers, Python lifecycle extensions+- Backend: API handlers, tools, helpers, Python lifecycle extensions, and implicit `@extensible` hooks- Frontend: WebUI components and extension-point injections- Agent profiles: plugin-scoped subagent definitions- Settings: scoped plugin configuration loaded through the plugin settings store@@ -64,12 +64,22 @@ usr/plugins/<plugin_name>/│ └── <profile>/agent.yaml # optional plugin-distributed agent profile├── extensions/│ ├── python/<extension_point>/+│ ├── python/_functions/<module>/<qualname>/<start|end>/│ └── webui/<extension_point>/└── webui/├── config.html # optional settings UI└── ...```+## Python Extension Layouts++Use one of these backend layouts:++- `extensions/python/<extension_point>/` for named lifecycle hooks such as `agent_init`, `system_prompt`, or `tool_execute_before`+- `extensions/python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` hook targets++The `_functions` layout keeps the full module path and nested `__qualname__` path, which avoids collisions between similarly named functions. Do not create the retired flattened form `extensions/python/<module>_<qualname>_<start|end>/`; it is stale and will not be resolved by the current extensible system.+## Python Imports for User PluginsFor plugin-local Python imports inside `usr/plugins/<plugin_name>/`, use thediff --git a/plugins/README.md b/plugins/README.mdindex cd2668f22..24d6f2f04 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -21,12 +21,18 @@ For detailed guides on how to create, extend, or configure plugins, refer to:Plugins are automatically discovered based on the presence of a `plugin.yaml` file. Each plugin can contribute:-- **Backend**: API handlers, tools, helpers, and lifecycle extensions+- **Backend**: API handlers, tools, helpers, named lifecycle extensions, and implicit `@extensible` hooks under `extensions/python/_functions/...`- **Frontend**: HTML/JS UI contributions via core extension breakpoints- **Settings**: Isolated configuration scoped per-project and per-agent profile- **Activation**: Global and scoped ON/OFF rules via `.toggle-1` and `.toggle-0` files, including advanced per-scope switching in the WebUI- **Agent profiles**: Plugin-distributed subagent definitions under `agents/<profile>/agent.yaml`+Backend extension layouts:+- `extensions/python/<point>/` for named lifecycle hooks+- `extensions/python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` hooks++Do not use the retired flattened `extensions/python/<module>_<qualname>_<start|end>/` form.+## Plugin ManifestEvery plugin requires a `plugin.yaml` at its root:diff --git a/plugins/_error_retry/README.md b/plugins/_error_retry/README.mdindex a37a371d2..90dffb56f 100644--- a/plugins/_error_retry/README.md+++ b/plugins/_error_retry/README.md@@ -22,8 +22,8 @@ It does **not** retry exceptions that are already treated as controlled agent fl## 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`+- `extensions/python/_functions/agent/Agent/monologue/start/_10_reset_critical_exception_counter.py`+- `extensions/python/_functions/agent/Agent/handle_exception/end/_80_retry_critical_exception.py`## Configuration Scopediff --git a/plugins/_plugin_installer/README.md b/plugins/_plugin_installer/README.mdindex 07c34213d..62b19450b 100644--- a/plugins/_plugin_installer/README.md+++ b/plugins/_plugin_installer/README.md@@ -1,6 +1,6 @@# Plugin Installer-Install and update Agent Zero plugins from ZIP uploads, Git repositories, or a community index.+Install and update Agent Zero plugins from ZIP uploads, Git repositories, or the community Plugin Index surfaced through the Plugin Hub.## What It Does@@ -20,8 +20,8 @@ This plugin provides the built-in installation workflow for third-party plugins.- 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.+- **Plugin Hub UI**+ - The web UI store handles browsing Plugin Index entries, showing README content, prompting about third-party plugin risk, and launching install/update actions.## Key Filesdiff --git a/plugins/_plugin_validator/webui/plugin-validator-checks.json b/plugins/_plugin_validator/webui/plugin-validator-checks.jsonindex 3d019620e..0a62c20d3 100644--- a/plugins/_plugin_validator/webui/plugin-validator-checks.json+++ b/plugins/_plugin_validator/webui/plugin-validator-checks.json@@ -16,7 +16,7 @@},"structure": {"label": "Structure Validation",- "detail": "Inspect the directory layout and role of each top-level file or folder. Check that api/ contains Python ApiHandler files, tools/ contains Tool subclasses, extensions/ follows python/<point>/ or webui/<point>/ conventions, webui/config.html is backed by settings_sections, hooks.py exposes install when expected, execute.py follows the main()/sys.exit(main()) pattern, and the root contains only expected plugin files. Also verify a file named LICENSE exists at the plugin root (same directory as plugin.yaml). Agent Zero does not require LICENSE for loading a local plugin, but the Plugin Index requires LICENSE at the repository root for community listings; a missing LICENSE must not be rated pass for this phase.",+ "detail": "Inspect the directory layout and role of each top-level file or folder. Check that api/ contains Python ApiHandler files, tools/ contains Tool subclasses, extensions/ follows python/<point>/, python/_functions/<module>/<qualname>/<start|end>/, or webui/<point>/ conventions, and flag the retired flattened python/<module>_<qualname>_<start|end>/ form if present. Also verify webui/config.html is backed by settings_sections, hooks.py exposes install when expected, execute.py follows the main()/sys.exit(main()) pattern, and the root contains only expected plugin files. Also verify a file named LICENSE exists at the plugin root (same directory as plugin.yaml). Agent Zero does not require LICENSE for loading a local plugin, but the Plugin Index requires LICENSE at the repository root for community listings; a missing LICENSE must not be rated pass for this phase.","criteria": {"pass": "Directory layout cleanly matches Agent Zero plugin conventions and LICENSE exists at the plugin root","warning": "Layout mostly works but LICENSE is missing at the plugin root (required for Plugin Index submission; optional for local-only use), or there are unusual files or minor convention drift",diff --git a/plugins/_plugin_validator/webui/plugin-validator-guidance.md b/plugins/_plugin_validator/webui/plugin-validator-guidance.mdindex 861192ece..64070051d 100644--- a/plugins/_plugin_validator/webui/plugin-validator-guidance.md+++ b/plugins/_plugin_validator/webui/plugin-validator-guidance.md@@ -1,6 +1,7 @@- Store gate pattern: wrap store-backed UI in `<template x-if="$store.myStore">` and mount cleanup on the inner element.- Store definition: use `createStore` from `/js/AlpineStore.js`; do not register Alpine stores inline in HTML or via `alpine:init`.- Notifications: use `toastFrontendError`, `toastFrontendSuccess`, or backend notification helpers; do not render inline error boxes.+- Python extensions: use `extensions/python/<point>/` for named lifecycle hooks and `extensions/python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` hooks. The flattened `extensions/python/<module>_<qualname>_<start|end>/` layout is stale and should be flagged.- API handlers: subclass `ApiHandler` and return a dict or `Response`.- Tools: subclass `Tool` from `helpers.tool`.- AgentContext imports: use `from agent import AgentContext, AgentContextType`, never `helpers.context`.diff --git a/plugins/_plugin_validator/webui/plugin-validator-prompt.md b/plugins/_plugin_validator/webui/plugin-validator-prompt.mdindex 0c19f812d..80fd2ceee 100644--- a/plugins/_plugin_validator/webui/plugin-validator-prompt.md+++ b/plugins/_plugin_validator/webui/plugin-validator-prompt.md@@ -20,7 +20,7 @@ Follow these steps in order:1. Resolve the plugin root and list every file below it. Do not sample; inspect the full plugin.2. Read `plugin.yaml` and record the plugin's name, title, description, and version.-3. Map the directory structure and identify every top-level file or folder that affects behavior. Record whether a `LICENSE` file exists at the plugin root (required for Plugin Index submission per project policy; optional for local-only plugins).+3. Map the directory structure and identify every top-level file or folder that affects behavior. Record whether backend extensions use named points under `extensions/python/<point>/`, implicit `@extensible` hooks under `extensions/python/_functions/<module>/<qualname>/<start|end>/`, or any stale flattened `extensions/python/<module>_<qualname>_<start|end>/` folders. Record whether a `LICENSE` file exists at the plugin root (required for Plugin Index submission per project policy; optional for local-only plugins).4. Run ONLY the selected validation phases listed below.5. If a temporary clone or extracted directory was used, perform the cleanup exactly as instructed.diff --git a/skills/a0-contribute-plugin/SKILL.md b/skills/a0-contribute-plugin/SKILL.mdindex f729483c3..ea5a4551f 100644--- a/skills/a0-contribute-plugin/SKILL.md+++ b/skills/a0-contribute-plugin/SKILL.md@@ -60,10 +60,12 @@ your-plugin-repo/ <- GitHub repository root├── prompts/ <- prompt templates├── agents/ <- agent profiles├── conf/ <- config files (e.g. model_providers.yaml)-├── extensions/ <- lifecycle and UI extensions+├── extensions/ <- lifecycle, UI, and implicit @extensible hooks└── webui/ <- frontend pages, stores, components```+Inside `extensions/`, use `python/<point>/` for named lifecycle hooks, `python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` hooks, and `webui/<point>/` for UI breakpoints. Do not publish the retired flattened `python/<module>_<qualname>_<start|end>/` form.+### Runtime `plugin.yaml` requirementsThe remote `plugin.yaml` must include a **`name` field** - this is validated by CI and must exactly match the index folder name:diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 97c91542b..ceefd391d 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -196,7 +196,8 @@ save_plugin_config(conf/model_providers.yaml # Optional: add or override model providersextensions/- python/agent_init/ # Python lifecycle extensions+ python/<extension_point>/ # Named Python lifecycle extensions+ python/_functions/<module>/<qualname>/<start|end>/ # Implicit @extensible hookswebui/<point>/ # HTML/JS hook extensionswebui/config.html # Optional: plugin settings UI@@ -204,6 +205,8 @@ save_plugin_config(my-store.js # Alpine stores```+Do not create the retired flattened extensible path form `extensions/python/<module>_<qualname>_<start|end>/`. The current runtime only resolves the deep `_functions/<module>/<qualname>/<start|end>` layout for implicit `@extensible` hooks.+### Import rule for plugin-local Python codeUse the fully qualified `usr.plugins.<plugin_name>...` path for plugin-localdiff --git a/skills/a0-debug-plugin/SKILL.md b/skills/a0-debug-plugin/SKILL.mdindex 46dc44f48..978ec39dd 100644--- a/skills/a0-debug-plugin/SKILL.md+++ b/skills/a0-debug-plugin/SKILL.md@@ -85,6 +85,11 @@ python3 -m py_compile /a0/usr/plugins/<name>/api/my_handler.py- Common breakpoints: `sidebar-quick-actions-main-start`, `plugins-list-header-buttons`, `chat-input-bottom-actions-end`- Confirm the HTML file has a root element with `x-data` and an `x-move-*` directive+For backend extension hooks:+- Named lifecycle hooks must live under `extensions/python/<point>/`+- Implicit `@extensible` hooks must live under `extensions/python/_functions/<module>/<qualname>/<start|end>/`+- The retired flattened form `extensions/python/<module>_<qualname>_<start|end>/` no longer loads+---## 6. Settings not saving / loading wrong values@@ -138,7 +143,7 @@ Plugin-related errors appear as Python tracebacks mentioning the plugin path.2. Any directory containing `plugin.yaml` is treated as a plugin3. `usr/plugins/<name>` takes priority over `plugins/<name>` when both exist (user overrides core)4. Toggle state is evaluated: `.toggle-0` disables, `.toggle-1` enables, no file = enabled by default-5. Enabled plugins have their `extensions/`, `api/`, `tools/`, etc. registered into the runtime+5. Enabled plugins have their `extensions/`, `api/`, `tools/`, etc. registered into the runtime, including both named extension points and implicit `_functions/...` extensible hooksPlugins are re-scanned when:- Agent Zero restartsdiff --git a/skills/a0-manage-plugin/SKILL.md b/skills/a0-manage-plugin/SKILL.mdindex b4f89b8be..032f1f5be 100644--- a/skills/a0-manage-plugin/SKILL.md+++ b/skills/a0-manage-plugin/SKILL.md@@ -127,6 +127,7 @@ If the scan times out or errors (500), inform the user and ask whether to proceeThe Plugin Hub marks a plugin as **Installed** by cross-referencing Plugin Hub keys against `usr/plugins/` directory names at request time. To appear installed:- The plugin directory must exist at `usr/plugins/<name>/` with a valid `plugin.yaml`+- If the plugin ships extensions, the framework will register both named extension points under `extensions/python/<point>/` and implicit `@extensible` hooks under `extensions/python/_functions/<module>/<qualname>/<start|end>/` after the plugin cache is refreshed- The framework plugin cache must be cleared (the API handles this automatically)- Re-fetching the Plugin Hub index will then show it as installeddiff --git a/skills/a0-plugin-router/SKILL.md b/skills/a0-plugin-router/SKILL.mdindex 8e559ddf9..8c8fbe174 100644--- a/skills/a0-plugin-router/SKILL.md+++ b/skills/a0-plugin-router/SKILL.md@@ -72,7 +72,7 @@ always_enabled: false # forces ON, disables toggle (framework use only)|---|---|| `api/` | API handlers (`ApiHandler` subclasses) || `tools/` | Agent tools (`Tool` subclasses) |-| `extensions/python/<point>/` | Backend lifecycle hooks |+| `extensions/python/<point>/` and `extensions/python/_functions/<module>/<qualname>/<start_or_end>/` | Backend lifecycle hooks and implicit `@extensible` hooks || `extensions/webui/<point>/` | HTML/JS injected into UI breakpoints || `webui/config.html` | Plugin settings UI || `webui/*.html`, `webui/*.js` | Full plugin pages and Alpine stores |@@ -84,6 +84,8 @@ always_enabled: false # forces ON, disables toggle (framework use only)| `conf/model_providers.yaml` | Add/override model providers || `LICENSE` | Optional under `usr/plugins/`; required at the root of a plugin GitHub repo before submitting to the Plugin Index |+For `@extensible` targets, the only valid implicit hook layout is `extensions/python/_functions/<module>/<qualname>/<start|end>/`. The older flattened `extensions/python/<module>_<qualname>_<start|end>/` folders are obsolete.+### Activation- Global toggle: `.toggle-1` (ON) / `.toggle-0` (OFF) files in the plugin dirdiff --git a/skills/a0-review-plugin/SKILL.md b/skills/a0-review-plugin/SKILL.mdindex 92f0d8933..05525dd2a 100644--- a/skills/a0-review-plugin/SKILL.md+++ b/skills/a0-review-plugin/SKILL.md@@ -46,7 +46,7 @@ Inspect the plugin directory layout:- [ ] Directory name matches `^[a-z0-9_]+$`- [ ] If `api/` exists: contains Python files only; each should subclass `ApiHandler`- [ ] If `tools/` exists: contains Python files only; each should subclass `Tool`-- [ ] If `extensions/` exists: check subdirs follow `python/<point>/` or `webui/<point>/` pattern+- [ ] If `extensions/` exists: check subdirs follow `python/<point>/`, `python/_functions/<module>/<qualname>/<start|end>/`, or `webui/<point>/` patterns; flag the retired flattened `python/<module>_<qualname>_<start|end>/` form- [ ] If `helpers/` exists: shared Python logic (standard directory)- [ ] If `prompts/` exists: prompt templates (standard directory)- [ ] If `agents/` exists: agent profiles with `<profile>/agent.yaml` (standard directory)diff --git a/skills/a0-review-plugin/checklists.md b/skills/a0-review-plugin/checklists.mdindex 76cea262d..734354360 100644--- a/skills/a0-review-plugin/checklists.md+++ b/skills/a0-review-plugin/checklists.md@@ -124,6 +124,32 @@ class MyTool(Tool):---+## Python Extension Layout++Use one of these backend extension layouts:++```text+extensions/python/<extension_point>/+```++For named lifecycle hooks such as `agent_init`, `system_prompt`, `monologue_start`, or `tool_execute_before`.++```text+extensions/python/_functions/<module>/<qualname>/<start|end>/+```++For implicit `@extensible` hook targets. The path must keep the full module path and every nested `__qualname__` segment.++**FAIL pattern**:++```text+extensions/python/<module>_<qualname>_<start|end>/+```++That flattened form is stale and no longer matches the current extensible runtime lookup.++---+## AgentContext Access```python