update docs
Alessandro committed
Feb 17, 2026 at 13:27 UTC
618179fa5bb2e992e3724a2ae50961a0149d307d
1 file changed
+71
-22
plugins/README.md
+71
-22
@@ -6,9 +6,9 @@ This directory contains default plugins shipped with Agent Zero.
6
7
Agent Zero uses a convention-over-configuration plugin model:
8
9
-- `plugin.json` is not used by runtime discovery.
9
- Runtime capabilities are discovered from directory structure.
11
-- Backend owns discovery and routing; frontend consumes resolved URLs.
10
+- Backend owns discovery, routing, and static asset serving.
11
+- Frontend uses explicit `x-extension` breakpoints plus the standard `x-component` loader.
12
13
## Directory Conventions
14
@@ -16,39 +16,88 @@ Each plugin lives in `plugins/<plugin_id>/` (or `usr/plugins/<plugin_id>/` for o
16
17
Capability discovery is based on these paths:
18
19
-- `api/*.py` - API handlers (`ApiHandler` subclasses), exposed as `/plugins/{plugin_id}/{handler_name}`
20
-- `tools/*.py` - Agent tools (`Tool` subclasses)
21
-- `helpers/*.py` - Shared Python helpers
22
-- `extensions/backend/{extension_point}/*.py` - Backend lifecycle extensions
23
-- `extensions/frontend/**/*.html` - Frontend UI components (auto-injected via `<meta name="plugin-target">`)
24
-- `prompts/**/*.md` - Prompt templates
25
-- `agents/` - Agent profiles
26
-- `extensions/frontend/` - Frontend UI assets and auto-injected components
19
+- `api/*.py` - API handlers (`ApiHandler` subclasses), exposed under `/api/plugins/<plugin_id>/<handler>`
20
+- `tools/*.py` - agent tools (`Tool` subclasses)
21
+- `helpers/*.py` - shared Python helpers
22
+- `extensions/python/<extension_point>/*.py` - backend lifecycle extensions
23
+- `extensions/webui/<extension_point>/*` - WebUI extension assets (HTML/JS)
24
+- `webui/**` - full plugin-owned UI pages/components (loaded directly by path)
25
+- `prompts/**/*.md` - prompt templates
26
+- `agents/` - agent profiles
27
28
-## Frontend Auto-Injection (PoC)
28
+## Frontend Extensions
29
30
-Plugins can inject HTML components into the core UI. Place components under `extensions/frontend/` and declare the injection target with a `<meta>` tag:
30
+### HTML insertion via breakpoints
31
+
32
+Core UI defines insertion points like:
33
34
```html
33
-<meta name="plugin-target" content=".quick-actions-dropdown">
35
+<x-extension id="sidebar-quick-actions-main-start"></x-extension>
36
```
37
36
-Components without the meta tag (e.g. modals, dashboards) are standalone and not auto-injected.
37
-
38
Resolution flow:
39
40
-TODO update:ú
40
+1. `webui/js/extensions.js` finds `x-extension` nodes.
41
+2. It calls `/api/load_webui_extensions` with the extension point and HTML filters.
42
+3. Backend returns matching files from `plugins/*/extensions/webui/<extension_point>/`.
43
+4. `extensions.js` injects returned entries as `<x-component path="...">`.
44
+5. `components.js` loads each component using the standard component pipeline.
45
+
46
+Baseline extension template (project convention):
47
+
48
+```html
49
+<div x-data>
50
+ <button
51
+ x-move-after=".config-button#dashboard"
52
+ class="config-button"
53
+ id="my-plugin-button"
54
+ @click="openModal('../plugins/my-plugin/webui/my-modal.html')"
55
+ title="My Plugin">
56
+ <span class="material-symbols-outlined">extension</span>
57
+ </button>
58
+</div>
59
+```
60
+
61
+Required baseline for HTML UI extensions in this repository:
62
+- include a root `x-data` scope
63
+- include one explicit `x-move-*` placement directive
64
+
65
+### JS hook extensions
66
+
67
+JS hooks are loaded from the same extension point structure:
68
+
69
+`plugins/<plugin_id>/extensions/webui/<extension_point>/*.js`
70
+
71
+Runtime code calls:
72
+
73
+`callJsExtensions("<extension_point>", ...args)`
74
+
75
+Example:
76
+
77
+`set_messages_before_loop` and `set_messages_after_loop` in `webui/js/messages.js`.
78
+
79
+### Fine placement helpers
80
+
81
+`initFw.js` provides Alpine move directives for plugin markup:
82
+
83
+- `x-move-to-start`
84
+- `x-move-to-end`
85
+- `x-move-to`
86
+- `x-move-before`
87
+- `x-move-after`
88
+
89
+## Plugin Author Flow
90
42
-1. The backend parses `<meta name="plugin-target">` from each component HTML at scan time.
43
-2. `/plugins_resolve` returns component URLs with their target selectors.
44
-3. TODO REM: `plugins.js` (loaded globally) creates `<x-component>` elements at the declared target selectors.
45
-4. The standard `components.js` MutationObserver handles loading automatically.
46
-5. A MutationObserver in `plugins.js` retries for targets that appear after initial page render.
91
+1. Pick an existing core breakpoint ID (`<x-extension id="...">`).
92
+2. Add an HTML/JS extension under `extensions/webui/<extension_point>/`.
93
+3. For HTML UI entries, use the baseline pattern: root `x-data` plus one explicit `x-move-*` directive.
94
+4. Put complete plugin pages/components in `webui/` and open them directly by path.
95
96
## Routes
97
98
- Plugin static assets: `GET /plugins/<plugin_id>/<path>`
51
-- Plugin APIs: `/plugins/<plugin_id>/<handler>`
99
+- Plugin APIs: `POST /api/plugins/<plugin_id>/<handler>`
100
+- WebUI extension discovery: `POST /api/load_webui_extensions`
101
102
## Notes
103