Agent Zero AI framework
add extension points coverage; add JS hooks
Alessandrob43cde0b4579
diff --git a/plugins/README.md b/plugins/README.mdindex 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 ConventionsEach 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.pyindex 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.htmlindex 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.jsindex 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 queuedif (!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.jsindex ba13dd1de..4f4ab9650 100644--- a/webui/js/modals.js+++ b/webui/js/modals.js@@ -1,5 +1,6 @@// Import the component loader and page utilitiesimport { importComponent } from "/js/components.js";+import { callJsExtensions } from "/js/extensions.js";// Modal functionalityconst 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 instanceconst 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 {