Agent Zero AI framework
update agents, human docs, plugin skill
Alessandro6f6348850d9f
diff --git a/AGENTS.md b/AGENTS.mdindex 529362c2a..f81ad76a6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,113 +1,216 @@-# Agent Zero — Full-Stack Agent & Plugin Architecture+# Agent Zero - AGENTS.md-This document bridges the gap between the **Python Backend** (AgentContext, LLM loop) and the **Frontend Component System** (Alpine.js, Modals). Use this as the canonical reference for building deep integrations.+[Generated using reconnaissance on 2026-02-22]++## Quick Reference+Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)+Dev Server: python run_ui.py (runs on http://localhost:50001 by default)+Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)+Documentation: README.md | docs/+Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](AGENTS.plugins.md)----## 1. The Core Concept: `AgentContext`+## Table of Contents+1. [Project Overview](#project-overview)+2. [Core Commands](#core-commands)+3. [Docker Environment](#docker-environment)+4. [Project Structure](#project-structure)+5. [Development Patterns & Conventions](#development-patterns--conventions)+6. [Safety and Permissions](#safety-and-permissions)+7. [Code Examples](#code-examples)+8. [Git Workflow](#git-workflow)+9. [API Documentation](#api-documentation)+10. [Troubleshooting](#troubleshooting)++----Every conversation in Agent Zero is an `AgentContext`. It owns the message history, the LLM state, the tool definitions, and the log queue.+## Project Overview-### Backend: Managing Contexts-When building a plugin, you must interact with the context system correctly:+Agent Zero is a dynamic, organic agentic framework designed to grow and learn. It uses the operating system as a tool, featuring a multi-agent cooperation model where every agent can create subordinates to break down tasks.-```python-from agent import AgentContext, AgentContextType, initialize_agent-from python.helpers.messages import UserMessage+Type: Full-Stack Agentic Framework (Python Backend + Alpine.js Frontend)+Status: Active Development+Primary Language(s): Python, JavaScript (ES Modules)-# 1. Access an existing context (e.g., from a stored ID)-context = AgentContext.use(context_id)+----# 2. Or create a new one-config = {} # use defaults-context = AgentContext(config=config, type=AgentContextType.USER)-await initialize_agent(context)+## Core Commands-# 3. Communicate (send a message and wait for completion)-task = context.communicate(UserMessage("Hello Agent!"))-response_text = await task.result()+### Setup+Do not combine these commands; run them individually:+```bash+pip install -r requirements.txt+pip install -r requirements2.txt```+- Start WebUI: python run_ui.py-### The Glue: `MessageQueue` (mq)-The frontend listens to a WebSocket. To make messages appear in the WebUI from your plugin, use the log helper:+----```python-# In your ApiHandler or bridge-from python.helpers.messages import mq+## Docker Environment-# This makes the user message appear in the UI immediately-mq.log_user_message(context.id, "Incoming message from WhatsApp", source="WhatsApp")-```+When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework from the code being executed:----+### 1. Framework Runtime (/opt/venv-a0)+- Version: Python 3.12.4+- Purpose: Runs the Agent Zero backend, API, and core logic.+- Packages: Contains all dependencies from requirements.txt.++### 2. Execution Runtime (/opt/venv)+- Version: Python 3.13+- Purpose: Default environment for the interactive terminal and the agent's code execution tool.+- Behavior: This is the environment active when you docker exec into the container. Packages installed by the agent via pip install during a task are stored here.-## 2. The Frontend: Component System+----Agent Zero uses a custom **Component Loader** that fetches HTML, extracts `<style>` and `<script type="module">`, and injects them into the DOM.+## Project Structure-### The "Golden Rules" of Frontend Components+```+/+├── agent.py # Core Agent and AgentContext definitions+├── initialize.py # Framework initialization logic+├── models.py # LLM provider configurations+├── run_ui.py # WebUI server entry point+├── python/+│ ├── api/ # API Handlers (ApiHandler subclasses)+│ ├── extensions/ # Backend lifecycle extensions+│ ├── helpers/ # Shared Python utilities (plugins, files, etc.)+│ ├── tools/ # Agent tools (Tool subclasses)+│ └── websocket_handlers/# WebSocket event handlers+├── webui/+│ ├── components/ # Alpine.js components+│ ├── js/ # Core frontend logic (modals, stores, etc.)+│ └── index.html # Main UI shell+├── usr/ # User data directory (isolated from core)+│ ├── plugins/ # Custom user plugins+│ ├── settings.json # User-specific configuration+│ └── workdir/ # Default agent workspace+├── plugins/ # Core system plugins+├── agents/ # Agent profiles (prompts and config)+├── prompts/ # System and message prompt templates+└── tests/ # Pytest suite+```-1. **Store Gating (Critical)**: Always wrap your component content in a template that waits for the store. This prevents "undefined" errors during the loading race.- ```html- <div x-data>- <template x-if="$store.myStore">- <div class="content">...</div>- </template>- </div>- ```-2. **Separate Store Files**: Never put store registration logic directly inside the HTML `alpine:init` block. Use a separate `*-store.js` file and import it via `<script type="module" src="...">`.-3. **createStore Proxy**: Use `createStore` from `/js/AlpineStore.js`. It ensures the store is available to the module even before Alpine fully boots.+Key Files:+- agent.py: Defines AgentContext and the main Agent class.+- python/helpers/plugins.py: Plugin discovery and configuration logic.+- webui/js/AlpineStore.js: Store factory for reactive frontend state.+- python/helpers/api.py: Base class for all API endpoints.+- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.+- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.+- AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.----## 3. The Modal System+## Development Patterns & Conventions++### Backend (Python)+- Context Access: Use from agent import AgentContext, AgentContextType (not python.helpers.context).+- Communication: Use mq from python.helpers.messages to log proactive UI messages:+ mq.log_user_message(context.id, "Message", source="Plugin")+- API Handlers: Derive from ApiHandler in python/helpers/api.py.+- Extensions: Use the extension framework in python/helpers/extension.py for lifecycle hooks.+- Error Handling: Use RepairableException for errors the LLM might be able to fix.++### Frontend (Alpine.js)+- Store Gating: Always wrap store-dependent content in a template:+```html+<div x-data>+ <template x-if="$store.myStore">+ <div x-init="$store.myStore.onOpen()">...</div>+ </template>+</div>+```+- Store Registration: Use createStore from /js/AlpineStore.js.+- Modals: Use openModal(path) and closeModal() from /js/modals.js.-Modals in A0 are "stacked" and loaded dynamically via `openModal(path)`.+### Plugin Architecture+- Location: Always develop new plugins in usr/plugins/.+- Manifest: Every plugin requires a plugin.json with name, description, version, and optionally settings_sections.+- Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).+- Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. For plugins wrapping core settings, set $store.pluginSettings.saveMode = 'core' in x-init.-### Directory Convention-- `webui/components/modals/<feature>/<feature>.html`-- `webui/components/modals/<feature>/<feature>-store.js`+### Lifecycle Synchronization+| Action | Backend Extension | Frontend Lifecycle |+|---|---|---|+| Initialization | agent_init | init() in Store |+| Mounting | N/A | x-create directive |+| Processing | monologue_start/end | UI loading state |+| Cleanup | context_deleted | x-destroy directive |-### Plugin Settings+----Plugins get a dedicated settings modal with **Project** and **Agent profile** context selectors. To enable it:+## Safety and Permissions-1. Add `webui/config.html` to your plugin (auto-detected).-2. Set `"settings_sections": ["agent"]` in `plugin.json` - this places a subsection with a Settings button in the chosen tab.+### Allowed Without Asking+- Read any file in the repository.+- Update code files in usr/.-Your `config.html` binds to `$store.pluginSettings.settings` (a plain object persisted as `config.json`). The modal's Save/Cancel footer handles persistence automatically. See `plugins/README.md` for the full contract and settings resolution priority chain.+### Ask Before Executing+- pip install (new dependencies).+- Deleting core files outside of usr/ or tmp/.+- Modifying agent.py or initialize.py.+- Making git commits or pushes.-For plugins that surface **existing core settings** (e.g. wrapping `settings/agent/memory.html`), set `$store.pluginSettings.saveMode = 'core'` in `x-init` to route Save through the core settings API instead.+### Never Do+- Commit, hardcode or leak secrets or .env files.+- Bypass CSRF or authentication checks.+- Hardcode API keys.----## 4. Lifecycle Synchronization+## Code Examples-| Action | Backend Extension | Frontend Lifecycle |-|---|---|---|-| **Initialization** | `agent_init` | `init()` in Store |-| **Mounting** | N/A | `x-create` directive |-| **Processing** | `monologue_start/end` | UI loading state |-| **Cleanup** | `context_deleted` | `x-destroy` directive |+### API Handler (Good)+```python+from python.helpers.api import ApiHandler, Request, Response++class MyHandler(ApiHandler):+ async def process(self, input: dict, request: Request) -> dict | Response:+ # Business logic here+ return {"ok": True, "data": "result"}+```++### Alpine Store (Good)+```javascript+import { createStore } from "/js/AlpineStore.js";++export const store = createStore("myStore", {+ items: [],+ init() { /* global setup */ },+ onOpen() { /* mount setup */ },+ cleanup() { /* unmount cleanup */ }+});+```++### Tool Definition (Good)+```python+from python.helpers.tool import Tool, ToolResult++class MyTool(Tool):+ async def execute(self, arg1: str):+ # Tool logic+ return ToolResult("Success")+```----## 5. Directory Mapping (Plugin Layout)--> [!IMPORTANT]-> **Always create new plugins in `usr/plugins/`.** The root `/plugins/` folder is reserved for core Agent Zero plugins and may be overwritten during framework updates.--```text-usr/plugins/my-plugin/-├── plugin.json # Required manifest (name, version, settings_sections)-├── api/ # ApiHandler (python.helpers.api)-├── extensions/-│ ├── python/agent_init/ # Auto-start logic-│ └── webui/ # sidebar-quick-actions-main-start/-└── webui/- ├── config.html # Optional: plugin settings UI- └── my-modal.html # Full plugin pages + stores+## Troubleshooting++### Dependency Conflicts+If pip install fails, try running in a clean virtual environment:+```bash+python -m venv .venv+source .venv/bin/activate+pip install -r requirements.txt+pip install -r requirements2.txt```-Refer to `docs/agents/AGENTS.components.md` for deep UI technicals and `docs/agents/AGENTS.modals.md` for modal-specific CSS classes (`btn-ok`, `btn-cancel`).+### WebSocket Connection Failures+- Check if X-CSRF-Token is being sent.+- Ensure the runtime ID in the session matches the current server instance.++---+*Last updated: 2026-02-22*+*Maintained by: Agent Zero Core Team*diff --git a/AGENTS.plugins.md b/AGENTS.plugins.mdnew file mode 100644index 000000000..cf3b9fd24--- /dev/null+++ b/AGENTS.plugins.md@@ -0,0 +1,91 @@+# Agent Zero - Plugins Guide++This guide covers the Python Backend and Frontend WebUI plugin architecture. Use this as the definitive reference for building and extending Agent Zero.++---++## 1. Architecture Overview++Agent Zero uses a convention-over-configuration plugin model where runtime capabilities are discovered from the directory structure.++### Internal Components++1. 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>/.+4. WebUI extensions (webui/js/extensions.js): Injects HTML/JS contributions into core UI breakpoints (x-extension).++---++## 2. File Structure++Each plugin lives in usr/plugins/<plugin_name>/.++```text+usr/plugins/<plugin_name>/+├── plugin.json # Required: Name, version, settings config+├── api/ # API handlers (ApiHandler subclasses)+├── tools/ # Agent tools (Tool subclasses)+├── helpers/ # Shared Python logic+├── prompts/ # Prompt templates+├── agents/ # Agent profiles+├── extensions/+│ ├── python/<point>/ # Backend lifecycle hooks+│ └── webui/<point>/ # UI HTML/JS contributions+└── webui/+ ├── config.html # Optional: Plugin settings UI+ └── ... # Full plugin pages/components+```++### plugin.json format+```json+{+ "name": "My Plugin",+ "description": "What this plugin does.",+ "version": "1.0.0",+ "settings_sections": ["agent"]+}+```+settings_sections values: agent, external, mcp, developer, backup.++---++## 3. Frontend Extensions++### HTML Breakpoints+Core UI defines insertion points like <x-extension id="sidebar-quick-actions-main-start"></x-extension>.+To contribute:+1. Place HTML files in extensions/webui/<extension_point>/.+2. Include a root x-data scope.+3. Include an x-move-* directive (e.g., x-move-to-start, x-move-after="#id").++### JS Hooks+Place *.js files in extensions/webui/<extension_point>/ and export a default async function. They are called via callJsExtensions("<point>", context).++---++## 4. Plugin Settings++1. Add webui/config.html to your plugin.+2. Bind fields to $store.pluginSettings.settings.+3. Settings are scoped per-project and per-agent automatically.++### Resolution Priority (Highest First)+1. project/.a0proj/agents/<profile>/plugins/<name>/config.json+2. project/.a0proj/plugins/<name>/config.json+3. usr/agents/<profile>/plugins/<name>/config.json+4. usr/plugins/<name>/config.json++---++## 5. Routes++| Route | Purpose |+|---|---|+| GET /plugins/<name>/<path> | Serve static assets |+| POST /api/plugins/<name>/<handler> | Call plugin API |+| POST /api/plugins | Management (action: get_config, save_config) |++---++*Refer to AGENTS.md for the main framework guide.*diff --git a/docs/agents/AGENTS.components.md b/docs/agents/AGENTS.components.mdindex 7d7ed73f1..31d564609 100644--- a/docs/agents/AGENTS.components.md+++ b/docs/agents/AGENTS.components.md@@ -7,11 +7,11 @@| Aspect | Value ||--------|-------|-| **Tech Stack** | Alpine.js, ES Modules, CSS Variables |-| **Component Tag** | `<x-component path="...">` |-| **State Management** | `createStore(name, model)` from `/js/AlpineStore.js` |-| **Modals** | `openModal(path)` / `closeModal()` from `/js/modals.js` |-| **API Layer** | `callJsonApi()` / `fetchApi()` from `/js/api.js` |+| Tech Stack | Alpine.js, ES Modules, CSS Variables |+| Component Tag | `<x-component path="...">` |+| State Management | `createStore(name, model)` from `/js/AlpineStore.js` |+| Modals | `openModal(path)` / `closeModal()` from `/js/modals.js` |+| API Layer | `callJsonApi()` / `fetchApi()` from `/js/api.js` |---@@ -182,7 +182,7 @@ This enables safe module-level initialization before Alpine loads.| Module import | `import { store } from "./feature-store.js"; store.prop` || Global (avoid) | `Alpine.store("featureStore").prop` |-**Prefer module imports over global lookups.**+Prefer module imports over global lookups.### Persistence Helpers@@ -262,7 +262,7 @@ const model = {};```-**Key distinction:**+Key distinction:- `init()` → once per app load (store registration)- `onOpen()` → each time component mounts (modal opens, etc.)- `cleanup()`/`destroy()` → teardown resources@@ -360,7 +360,7 @@ Parent `x-component` attributes accessible via `globalThis.xAttrs(element)`:</div>```-**Always gate components that depend on stores.** Prevents errors during initial load race.+Always gate components that depend on stores. Prevents errors during initial load race.---@@ -422,7 +422,7 @@ When `x-component` wrapper would break flex layout:### Common Mistakes-**Race condition: store not ready**+Race condition: store not ready```html<!-- ❌ BAD: No gate --><div x-data>@@ -437,7 +437,7 @@ When `x-component` wrapper would break flex layout:</div>```-**Duplicate initialization**+Duplicate initialization```javascript// ❌ BAD: Runs every time store accessedinit() {@@ -452,7 +452,7 @@ init() {}```-**Leaking listeners**+Leaking listeners```javascript// ❌ BAD: No cleanupinit() {@@ -474,7 +474,7 @@ destroy() {### Minimum Requirements for External Apps-1. **Files to copy:**+1. Files to copy:```/js/components.js # Component loader/js/AlpineStore.js # Store factory@@ -482,11 +482,11 @@ destroy() {/js/initFw.js # Alpine bootstrap + directives```-2. **Dependencies:**+2. Dependencies:- Alpine.js (vendor or CDN)- CSS variables (define your theme)-3. **Bootstrap sequence:**+3. Bootstrap sequence:```javascript// initFw.js pattern:await import("path/to/alpine.min.js");@@ -497,7 +497,7 @@ destroy() {// etc.```-4. **HTML entry point:**+4. HTML entry point:```html<script type="module" src="/js/initFw.js"></script><x-component path="app/root.html"></x-component>@@ -516,10 +516,10 @@ destroy() {| Framework | Consideration ||-----------|--------------|-| **Vanilla/Static** | Works directly, include initFw.js |-| **Electron** | Works, may need CSP adjustments for Blob URLs |-| **React/Vue** | Mount Alpine in specific container, avoid conflicts |-| **SPA Routers** | MutationObserver handles dynamic inserts |+| Vanilla/Static | Works directly, include initFw.js |+| Electron | Works, may need CSP adjustments for Blob URLs |+| React/Vue | Mount Alpine in specific container, avoid conflicts |+| SPA Routers | MutationObserver handles dynamic inserts |---@@ -551,7 +551,7 @@ webui/components/└── ...```-**Naming conventions:**+Naming conventions:- Components: `feature-name.html`- Stores: `feature-store.js` or `feature-name-store.js`- Modals: placed in `modals/` or feature folderdiff --git a/docs/agents/AGENTS.modals.md b/docs/agents/AGENTS.modals.mdindex 86fd4a5fa..3b75f84bd 100644--- a/docs/agents/AGENTS.modals.md+++ b/docs/agents/AGENTS.modals.md@@ -149,7 +149,7 @@ Use these standard button classes for modal actions:| `btn btn-ok` | Positive/confirmatory actions (Save, Create, Confirm) | Solid blue background, white text || `btn btn-cancel` | Dismissive/negative actions (Cancel, Close, Delete) | Transparent with accent border |-Footer button order convention: **positive action first** (left), **negative action second** (right).+Footer button order convention: positive action first (left), negative action second (right).Example footer markup:diff --git a/plugins/README.md b/plugins/README.mdindex 68772935e..b793a763d 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -1,199 +1,22 @@-# Agent Zero Plugins+# Agent Zero - Core Plugins-This directory contains default plugins. For a full-stack development guide, see [docs/AGENTS.md](../docs/AGENTS.md).+This directory contains the system-level plugins for Agent Zero.-> [!TIP]-> While Agent Zero looks for plugins in both `usr/plugins/` and `plugins/`, you should **always develop new plugins in `usr/plugins/`**. This ensures your work is isolated from core system files and persists through framework updates.+## Directory Structure-## Architecture+- plugins/: Core system plugins (reserved for framework updates).+- usr/plugins/: Recommended location for user-developed plugins.-Agent Zero uses a convention-over-configuration plugin model:+## Documentation-- Runtime capabilities are discovered from directory structure.-- Backend owns discovery, routing, and static asset serving.-- Frontend uses explicit `x-extension` breakpoints plus the standard `x-component` loader.+For detailed guides on how to create, extend, or configure plugins, please refer to:-### Internal Components+- AGENTS.plugins.md: Full-stack plugin architecture, manifest format, and extension points.+- AGENTS.md: Main framework guide and backend context overview.-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>/`.+## Usage-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-usr/plugins/- <plugin_name>/- plugin.json # Required manifest (enables discovery)- 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/- config.html # Optional: plugin settings UI- ... # Full plugin-owned UI pages/components-```--## Directory Conventions--Each plugin lives in `usr/plugins/<plugin_name>/`.--Capability discovery is based on these paths:--- `plugin.json` - **required** manifest; a directory without it is not recognized as a plugin-- `api/*.py` - API handlers (`ApiHandler` subclasses), exposed under `/api/plugins/<plugin_name>/<handler>`-- `tools/*.py` - agent tools (`Tool` subclasses)-- `helpers/*.py` - shared Python helpers-- `extensions/python/<extension_point>/*.py` - backend lifecycle extensions-- `extensions/webui/<extension_point>/*` - WebUI extension assets (HTML/JS)-- `webui/**` - full plugin-owned UI pages/components (loaded directly by path)-- `webui/config.html` - if present, a Settings button appears for this plugin in the relevant settings tabs-- `prompts/**/*.md` - prompt templates-- `agents/` - agent profiles--### `plugin.json` format--```json-{- "name": "My Plugin",- "description": "What this plugin does.",- "version": "1.0.0",- "settings_sections": ["agent"]-}-```--`settings_sections` controls which Settings tabs show a subsection for this plugin. Current valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Leave empty (`[]`) for no subsection.--## Frontend Extensions--### HTML insertion via breakpoints--Core UI defines insertion points like:--```html-<x-extension id="sidebar-quick-actions-main-start"></x-extension>-```--Resolution flow:--1. `webui/js/extensions.js` finds `x-extension` nodes.-2. It calls `/api/load_webui_extensions` with the extension point and HTML filters.-3. Backend returns matching files from `plugins/*/extensions/webui/<extension_point>/`.-4. `extensions.js` injects returned entries as `<x-component path="...">`.-5. `components.js` loads each component using the standard component pipeline.--Required baseline for HTML UI extensions in this repository:-- include a root `x-data` scope-- include one explicit `x-move-*` placement directive--### JS hook extensions--JS hooks are loaded from the same extension point structure:--`plugins/<plugin_id>/extensions/webui/<extension_point>/*.js`--Runtime code calls:--`callJsExtensions("<extension_point>", contextObject)`--### Fine placement helpers--`initFw.js` provides Alpine move directives for plugin markup:--- `x-move-to-start`-- `x-move-to-end`-- `x-move-to`-- `x-move-before`-- `x-move-after`--## Plugin Settings--If your plugin needs user-configurable settings:--1. Add `webui/config.html` to your plugin. The system detects this file automatically.-2. Declare which settings tabs should show a subsection for your plugin via `settings_sections` in `plugin.json`.-3. The plugin settings modal provides **Project** and **Agent profile** context selectors (same as the Skills list). Settings are scoped per-project and per-agent.--### Config HTML contract--Your `config.html` receives context from `$store.pluginSettings`:--```html-<html>-<head>- <title>My Plugin Config</title>- <script type="module">- import { store } from "/components/plugins/plugin-settings-store.js";- </script>-</head>-<body>- <div x-data>- <!-- bind fields to $store.pluginSettings.settings -->- <input x-model="$store.pluginSettings.settings.my_key" />- </div>-</body>-</html>-```--- `$store.pluginSettings.settings` - plain object loaded from `config.json`, save-scoped to the selected project/agent.-- The modal's **Save** button calls `POST /plugins` (`action: save_config`) automatically.-- For plugins that surface **core settings** (like memory), set `saveMode = 'core'` in `x-init` so Save delegates to the core settings API instead.--### Settings resolution priority (highest first)--```-project/.a0proj/agents/<profile>/plugins/<name>/config.json-project/.a0proj/plugins/<name>/config.json-usr/agents/<profile>/plugins/<name>/config.json-agents/<profile>/plugins/<name>/config.json-usr/plugins/<name>/config.json-plugins/<name>/config.json-```--## Plugin Author Flow--1. Create `usr/plugins/<plugin_name>/`.-2. Add `plugin.json` manifest (required for discovery).-3. Add backend capabilities by convention (`api/`, `tools/`, `helpers/`, `extensions/python/`, `prompts/`, `agents/`).-4. Pick a WebUI breakpoint or JS hook extension point.-5. For HTML UI entries: place files under `extensions/webui/<extension_point>/`, use root `x-data` + one `x-move-*` directive.-6. For JS hooks: place `*.js` files under `extensions/webui/<extension_point>/`, export a default async function.-7. Place full plugin pages/components in `webui/` and open them directly by path.-8. Optionally add `webui/config.html` and set `settings_sections` in `plugin.json` to expose settings in the UI.--## Routes--- Plugin static assets: `GET /plugins/<plugin_name>/<path>`-- Plugin APIs: `POST /api/plugins/<plugin_name>/<handler>`-- WebUI extension discovery: `POST /api/load_webui_extensions`-- Plugin management (get/save config): `POST /plugins`--## Notes--- 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).-- When you need a new extension point for your plugin, submit a PR - we are actively expanding coverage based on community needs.+Plugins are automatically discovered based on the presence of a plugin.json file. Each plugin can contribute:+- Backend: APIs, Tools, Helpers, and Lifecycle Extensions.+- Frontend: HTML/JS UI contributions via core breakpoints.+- Config: Isolated settings scoped per-project and per-agent profile.diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 8a02d5adb..2d7e0df01 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -6,17 +6,17 @@ description: Create, extend, or modify Agent Zero plugins. Follows strict full-s# Agent Zero Plugin Development> [!IMPORTANT]-> **Always create new plugins in `usr/plugins/<plugin_name>/`.** The root `/plugins` directory is reserved for core system plugins.+> Always create new plugins in usr/plugins/<plugin_name>/. The root /plugins directory is reserved for core system plugins.Primary references:-- `/a0/AGENTS.md` (Full-stack architecture & AgentContext)-- `/a0/docs/agents/AGENTS.components.md` (Component system deep dive)-- `/a0/docs/agents/AGENTS.modals.md` (Modal system & CSS conventions)-- `/a0/plugins/README.md` (Extension points, plugin.json, settings system)+- /a0/AGENTS.md (Full-stack architecture & AgentContext)+- /a0/docs/agents/AGENTS.components.md (Component system deep dive)+- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)+- /a0/AGENTS.plugins.md (Extension points, plugin.json, settings system)-## 📋 Plugin Manifest (`plugin.json`)+## Plugin Manifest (plugin.json)-Every plugin **must** have a `plugin.json` or it will not be discovered:+Every plugin must have a plugin.json or it will not be discovered:```json{@@ -27,12 +27,12 @@ Every plugin **must** have a `plugin.json` or it will not be discovered:}```-`settings_sections` controls which Settings tabs show a subsection for this plugin. Valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Use `[]` for no subsection.+settings_sections controls which Settings tabs show a subsection for this plugin. Valid values: agent, external, mcp, developer, backup. Use [] for no subsection.-## 🛠️ Mandatory Frontend Patterns+## Mandatory Frontend Patterns### 1. The "Store Gate" Template-To avoid race conditions and "undefined" errors, every component must use this wrapper:+To avoid race conditions and undefined errors, every component must use this wrapper:```html<div x-data><template x-if="$store.myPluginStore">@@ -44,30 +44,31 @@ To avoid race conditions and "undefined" errors, every component must use this w```### 2. Separate Store Module-Place store logic in a separate `.js` file. Do NOT use `alpine:init` listeners inside HTML.+Place store logic in a separate .js file. Do NOT use alpine:init listeners inside HTML.```javascript// webui/my-store.jsimport { createStore } from "/js/AlpineStore.js";export const store = createStore("myPluginStore", {status: 'idle',init() { ... },- onOpen() { ... }+ onOpen() { ... },+ cleanup() { ... }});```-Import it in the HTML `<head>`:+Import it in the HTML <head>:```html<head><script type="module" src="/plugins/<plugin_name>/webui/my-store.js"></script></head>```-## ⚙️ Plugin Settings+## Plugin Settings-If your plugin needs user-configurable settings, add `webui/config.html`. The system detects it automatically and shows a Settings button in the relevant tabs (per `settings_sections` in `plugin.json`).+If your plugin needs user-configurable settings, add webui/config.html. The system detects it automatically and shows a Settings button in the relevant tabs (per settings_sections in plugin.json).### Settings modal contract-The modal provides Project + Agent profile context selectors. Your `config.html` binds to `$store.pluginSettings.settings`:+The modal provides Project + Agent profile context selectors. Your config.html binds to $store.pluginSettings.settings:```html<html>@@ -86,11 +87,11 @@ The modal provides Project + Agent profile context selectors. Your `config.html`</html>```-The modal's Save button persists `$store.pluginSettings.settings` to `config.json` in the correct scope (project/agent/global).+The modal's Save button persists $store.pluginSettings.settings to config.json in the correct scope (project/agent/global).### Surfacing core settings (e.g. memory pattern)-If your plugin exposes **existing core settings** rather than plugin-specific ones, set `saveMode = 'core'` so Save delegates to the core settings API:+If your plugin exposes existing core settings rather than plugin-specific ones, set saveMode = 'core' so Save delegates to the core settings API:```html<div x-data x-init="@@ -102,15 +103,16 @@ If your plugin exposes **existing core settings** rather than plugin-specific on```### Sidebar Button (sidebar entry point)-- **Extension point**: `sidebar-quick-actions-main-start`-- **Class**: `class="config-button"`-- **Placement**: `x-move-after=".config-button#dashboard"`-- **Action**: `@click="openModal('/plugins/<plugin_name>/webui/my-modal.html')"`+- Extension point: sidebar-quick-actions-main-start+- Class: class="config-button"+- Placement: x-move-after=".config-button#dashboard"+- Action: @click="openModal('/plugins/<plugin_name>/webui/my-modal.html')"-## 🐍 Backend API & Context+## Backend API & Context### Import Paths-- **Correct**: `from agent import AgentContext` (not python.helpers.agent)+- Correct: from agent import AgentContext, AgentContextType+- Correct: from initialize import initialize_agent### Sending Messages Proactively```python@@ -138,7 +140,7 @@ save_plugin_config()```-## 📁 Directory Layout+## Directory Layout```usr/plugins/<name>/plugin.json # Required manifest