Skip to content

Agent Zero AI framework

add extension points coverage; add JS hooks

Alessandrob43cde0b4579
diff --git a/plugins/README.md b/plugins/README.md
index 6404c5e9c..8b7c84344 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -1,6 +1,6 @@
# Agent Zero Plugins
-This directory contains default plugins shipped with Agent Zero.
+This directory contains default plugins shipped with Agent Zero and is the source of truth for the plugin system.
## Architecture
@@ -10,6 +10,49 @@ Agent Zero uses a convention-over-configuration plugin model:
- Backend owns discovery, routing, and static asset serving.
- Frontend uses explicit `x-extension` breakpoints plus the standard `x-component` loader.
+### Internal Components
+
+1. **Backend plugin discovery** (`python/helpers/plugins.py`)
+ - `get_plugin_roots()` resolves roots in priority order (`usr/plugins` first, then `plugins`).
+ - `list_plugins()` builds the effective set (first root wins on ID conflicts).
+ - `get_webui_extensions(extension_point, filters)` scans `extensions/webui/<extension_point>/`.
+
+2. **Path resolution** (`python/helpers/subagents.py`)
+ - `get_paths(..., include_plugins=True)` includes plugin candidates for prompts/tools.
+
+3. **Python extension runtime** (`python/helpers/extension.py`)
+ - `call_extensions(extension_point, agent, **kwargs)` executes extension classes.
+ - Searches `python/extensions/<point>/` and `plugins/*/extensions/python/<point>/`.
+ - Extension classes derive from `Extension` and implement `async execute()`.
+
+4. **API and static routes** (`run_ui.py`, `python/api/load_webui_extensions.py`)
+ - `GET /plugins/<plugin_id>/<path>` serves plugin static assets.
+ - Plugin APIs are mounted under `/api/plugins/<plugin_id>/<handler>`.
+ - `POST /api/load_webui_extensions` returns extension files for a given extension point.
+
+5. **Frontend WebUI extension runtime** (`webui/js/extensions.js`)
+ - HTML flow: discovers `<x-extension>` tags, calls backend API, injects `<x-component>` tags.
+ - JS flow: `callJsExtensions("<extension_point>", contextObject)` loads and executes plugin JS modules.
+ - Both HTML and JS lookups are cached per extension point.
+
+## File Structure
+
+```text
+plugins/
+ <plugin_id>/
+ api/ # API handlers (ApiHandler subclasses)
+ tools/ # Agent tools (Tool subclasses)
+ helpers/ # Shared Python helpers
+ prompts/ # Prompt templates
+ agents/ # Agent profiles
+ extensions/
+ python/<extension_point>/ # Python lifecycle extensions
+ webui/<extension_point>/ # WebUI HTML/JS hook contributions
+ webui/ # Full plugin-owned UI pages/components
+
+usr/plugins/<plugin_id>/ # User overrides (higher priority)
+```
+
## Directory Conventions
Each plugin lives in `plugins/<plugin_id>/` (or `usr/plugins/<plugin_id>/` for overrides).
@@ -72,6 +115,10 @@ Current welcome surfaces:
- `welcome-screen-start`
- `welcome-screen-end`
+- `welcome-actions-start`
+- `welcome-actions-end`
+- `welcome-banners-start`
+- `welcome-banners-end`
Current modal surfaces:
@@ -117,15 +164,23 @@ JS hooks are loaded from the same extension point structure:
Runtime code calls:
-`callJsExtensions("<extension_point>", ...args)`
+`callJsExtensions("<extension_point>", contextObject)`
JS hook convention:
- pass one mutable context object when extensions are expected to influence behavior
- that object is passed by reference, so mutations are visible to subsequent hooks in the same flow
+- hooks that support cancellation expose a `cancel: false` or `skip: false` field; set it to `true` to abort the operation
-Example:
+Current JS hook points:
-`set_messages_before_loop` and `set_messages_after_loop` in `webui/js/messages.js`.
+| Hook | File | Context fields | skip/cancel |
+|---|---|---|---|
+| `set_messages_before_loop` | messages.js | `messages, history, scrollerOptions, massRender, results` | - |
+| `set_messages_after_loop` | messages.js | same as above | - |
+| `send_message_before` | index.js | `message, attachments, context, cancel` | `cancel` |
+| `apply_snapshot_before` | index.js | `snapshot, willUpdateMessages, skip` | `skip` |
+| `open_modal_before` | modals.js | `modalPath, modal, cancel` | `cancel` |
+| `close_modal_before` | modals.js | `modalPath, modal, cancel` | `cancel` |
### Fine placement helpers
@@ -145,10 +200,56 @@ Placement behavior:
## Plugin Author Flow
-1. Pick an existing core breakpoint ID (`<x-extension id="...">`).
-2. Add an HTML/JS extension under `extensions/webui/<extension_point>/`.
-3. For HTML UI entries, use the baseline pattern: root `x-data` plus one explicit `x-move-*` directive.
-4. Put complete plugin pages/components in `webui/` and open them directly by path.
+1. Create `plugins/<plugin_id>/`.
+2. Add backend capabilities by convention (`api/`, `tools/`, `helpers/`, `extensions/python/`, `prompts/`, `agents/`).
+3. Pick a WebUI breakpoint or JS hook extension point.
+4. For HTML UI entries: place files under `extensions/webui/<extension_point>/`, use root `x-data` + one `x-move-*` directive.
+5. For JS hooks: place `*.js` files under `extensions/webui/<extension_point>/`, export a default async function.
+6. Place full plugin pages/components in `webui/` and open them directly by path.
+
+### Python extension example
+
+```python
+# plugins/my-plugin/extensions/python/monologue_end/_50_my_extension.py
+from python.helpers.extension import Extension
+
+class MyExtension(Extension):
+ async def execute(self, **kwargs):
+ pass
+```
+
+### HTML WebUI extension example
+
+```html
+<!-- plugins/my-plugin/extensions/webui/sidebar-quick-actions-main-start/my-button.html -->
+<div x-data>
+ <button
+ x-move-after=".config-button#dashboard"
+ class="config-button"
+ id="my-plugin-button"
+ @click="openModal('../plugins/my-plugin/webui/my-modal.html')"
+ title="My Plugin">
+ <span class="material-symbols-outlined">extension</span>
+ </button>
+</div>
+```
+
+### JS hook example
+
+```js
+// plugins/my-plugin/extensions/webui/send_message_before/transform.js
+export default async function(ctx) {
+ // prepend a tag to every outgoing message
+ ctx.message = "[my-plugin] " + ctx.message;
+}
+```
+
+### Full plugin UI page
+
+```html
+<!-- opened via openModal() or x-component -->
+<x-component path="../plugins/my-plugin/webui/my-modal.html"></x-component>
+```
## Routes
@@ -160,3 +261,6 @@ Placement behavior:
- User plugins in `usr/plugins/` override repo plugins by plugin ID.
- Runtime behavior is fully convention-driven from directory structure.
+- Extension point ordering between multiple plugins is currently implicit (filesystem order).
+- Project-specific plugin roots are not yet active (commented out in `get_plugin_roots()`).
+- When you need a new extension point for your plugin, submit a PR - we are actively expanding coverage based on community needs.
diff --git a/plugins/tests/test_webui_extension_surfaces.py b/plugins/tests/test_webui_extension_surfaces.py
index 186de038d..b7b60235f 100644
--- a/plugins/tests/test_webui_extension_surfaces.py
+++ b/plugins/tests/test_webui_extension_surfaces.py
@@ -44,6 +44,10 @@ SURFACE_SCENARIOS: list[tuple[str, str]] = [
("chat-top-end", "webui/components/chat/top-section/chat-top.html"),
("welcome-screen-start", "webui/components/welcome/welcome-screen.html"),
("welcome-screen-end", "webui/components/welcome/welcome-screen.html"),
+ ("welcome-actions-start", "webui/components/welcome/welcome-screen.html"),
+ ("welcome-actions-end", "webui/components/welcome/welcome-screen.html"),
+ ("welcome-banners-start", "webui/components/welcome/welcome-screen.html"),
+ ("welcome-banners-end", "webui/components/welcome/welcome-screen.html"),
("modal-shell-start", "webui/js/modals.js"),
("modal-shell-end", "webui/js/modals.js"),
]
diff --git a/webui/components/welcome/welcome-screen.html b/webui/components/welcome/welcome-screen.html
index ba76d8e59..63ff0ce49 100644
--- a/webui/components/welcome/welcome-screen.html
+++ b/webui/components/welcome/welcome-screen.html
@@ -14,6 +14,7 @@
<div class="welcome-content">
<!-- Action Cards -->
<div class="welcome-actions">
+ <x-extension id="welcome-actions-start"></x-extension>
<div class="welcome-action-card" @click="$store.welcomeStore.executeAction('new-chat')">
<span class="material-symbols-outlined welcome-action-icon">add_circle</span>
<h3 class="welcome-action-title">New Chat</h3>
@@ -49,6 +50,7 @@
<span class="material-symbols-outlined welcome-action-icon">code</span>
<h3 class="welcome-action-title">Visit GitHub</h3>
</div>
+ <x-extension id="welcome-actions-end"></x-extension>
</div>
<div class="welcome-actions-footer">
@@ -72,6 +74,7 @@
<!-- Banner Section -->
<div class="welcome-banners" x-show="$store.welcomeStore.banners && $store.welcomeStore.banners.length > 0">
+ <x-extension id="welcome-banners-start"></x-extension>
<template x-for="banner in $store.welcomeStore.sortedBanners" :key="banner.id">
<div class="welcome-banner" :class="$store.welcomeStore.getBannerClass(banner.type)">
<!-- Banner Icon -->
@@ -94,6 +97,7 @@
</button>
</div>
</template>
+ <x-extension id="welcome-banners-end"></x-extension>
</div>
</div>
<x-extension id="welcome-screen-end"></x-extension>
@@ -116,7 +120,9 @@
position: relative;
overflow: hidden;
}
- .welcome-container > x-extension {
+ .welcome-container > x-extension,
+ .welcome-actions > x-extension,
+ .welcome-banners > x-extension {
display: contents;
}
diff --git a/webui/index.js b/webui/index.js
index a25cc3b6d..fe0e9d091 100644
--- a/webui/index.js
+++ b/webui/index.js
@@ -1,5 +1,6 @@
import * as msgs from "/js/messages.js";
import * as api from "/js/api.js";
+import { callJsExtensions } from "/js/extensions.js";
import * as css from "/js/css.js";
import { sleep } from "/js/sleep.js";
import { store as attachmentsStore } from "/components/chat/attachments/attachmentsStore.js";
@@ -38,10 +39,16 @@ let skipOneSpeech = false;
export async function sendMessage() {
try {
- const message = inputStore.message.trim();
- const attachmentsWithUrls = attachmentsStore.getAttachmentsForSending();
+ let message = inputStore.message.trim();
+ let attachmentsWithUrls = attachmentsStore.getAttachmentsForSending();
const hasAttachments = attachmentsWithUrls.length > 0;
+ const sendCtx = { message, attachments: attachmentsWithUrls, context, cancel: false };
+ await callJsExtensions("send_message_before", sendCtx);
+ if (sendCtx.cancel) return;
+ message = sendCtx.message;
+ attachmentsWithUrls = sendCtx.attachments;
+
// If empty input but has queued messages, send all queued
if (!message && !hasAttachments && messageQueueStore.hasQueue) {
await messageQueueStore.sendAll();
@@ -311,6 +318,14 @@ export async function applySnapshot(snapshot, options = {}) {
return { updated: false };
}
+ const snapCtx = {
+ snapshot,
+ willUpdateMessages: lastLogVersion != snapshot.log_version,
+ skip: false,
+ };
+ await callJsExtensions("apply_snapshot_before", snapCtx);
+ if (snapCtx.skip) return { updated: false };
+
// If the chat has been reset, reset cursors and request a resync from the caller.
// Note: on first snapshot after a context switch, lastLogGuid is intentionally empty,
// so the mismatch is expected and should not trigger a second state_request/poll.
diff --git a/webui/js/modals.js b/webui/js/modals.js
index ba13dd1de..4f4ab9650 100644
--- a/webui/js/modals.js
+++ b/webui/js/modals.js
@@ -1,5 +1,6 @@
// Import the component loader and page utilities
import { importComponent } from "/js/components.js";
+import { callJsExtensions } from "/js/extensions.js";
// Modal functionality
const modalStack = [];
@@ -106,12 +107,18 @@ function createModalElement(path) {
}
// Function to open modal with content from URL
-export function openModal(modalPath, beforeClose = null) {
+export async function openModal(modalPath, beforeClose = null) {
+ const openCtx = { modalPath, modal: null, cancel: false };
+ await callJsExtensions("open_modal_before", openCtx);
+ if (openCtx.cancel) return;
+ modalPath = openCtx.modalPath;
+
return new Promise((resolve) => {
try {
// Create new modal instance
const modal = createModalElement(modalPath);
modal.beforeClose = beforeClose;
+ openCtx.modal = modal;
new MutationObserver(
(_, o) =>
@@ -175,7 +182,7 @@ export function openModal(modalPath, beforeClose = null) {
}
// Function to close modal
-export function closeModal(modalPath = null) {
+export async function closeModal(modalPath = null) {
if (modalStack.length === 0) return;
let modalIndex = modalStack.length - 1; // Default to last modal
@@ -193,6 +200,10 @@ export function closeModal(modalPath = null) {
modal = modalStack[modalStack.length - 1];
}
+ const closeCtx = { modalPath: modalPath ?? null, modal, cancel: false };
+ await callJsExtensions("close_modal_before", closeCtx);
+ if (closeCtx.cancel) return false;
+
const canClose = async () => {
if (!modal.beforeClose) return true;
try {