| 1 | # Plugins DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own bundled system plugins shipped with Agent Zero. |
| 6 | - Provide the tracked plugin architecture contract for both bundled plugins and custom plugins developed under ignored `usr/plugins/`. |
| 7 | - Keep plugin behavior discoverable, reversible, and compatible across bundled and custom roots without creating DOX files inside `usr/`. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - Each direct `_plugin_name/` directory owns its `plugin.yaml`, optional `default_config.yaml`, `hooks.py`, API handlers, helpers, tools, prompts, skills, extensions, WebUI assets, and README. |
| 12 | - Plugins may also own `execute.py`, `conf/model_providers.yaml`, plugin-distributed `agents/<profile>/agent.yaml`, static assets, and plugin-local docs. |
| 13 | - `README.md` owns the high-level core plugin architecture summary and community Plugin Index guidance. |
| 14 | - Custom or experimental user plugins belong under `usr/plugins/`, not here, but this file remains their tracked DOX contract. |
| 15 | - Do not create `AGENTS.md` files under `usr/plugins/` unless the user explicitly asks for ignored user-state documentation. |
| 16 | |
| 17 | ## Local Contracts |
| 18 | |
| 19 | - Every plugin directory must include a valid `plugin.yaml`. |
| 20 | - Bundled plugin directory names and manifest `name` values must start with `_` to avoid collisions with community plugins. |
| 21 | - Runtime manifest fields include `name`, `title`, `description`, `version`, `settings_sections`, `per_project_config`, `per_agent_config`, and `always_enabled`. |
| 22 | - Core plugins may use `plugins.<plugin_name>...` imports when they are shipped from this tree. |
| 23 | - User plugins under `usr/plugins/` must use `usr.plugins.<plugin_name>...` imports and avoid `sys.path` hacks or persistent symlink-based imports. |
| 24 | - Plugin extension layouts must use `extensions/python/<point>/`, `extensions/python/_functions/<module>/<qualname>/<start|end>/`, and `extensions/webui/<point>/`. |
| 25 | - The `_functions` extension layout preserves every module and nested qualname segment; do not use retired flattened extension folder names. |
| 26 | - Plugin settings defaults belong in `default_config.yaml`; runtime user settings belong under `usr/`. |
| 27 | - Plugin settings resolution order is project/profile, project, user/profile, user plugin config, then bundled `default_config.yaml`. |
| 28 | - `webui/config.html` settings UIs must bind plugin values to `config.*` and modal state/actions to `context.*` through `$store.pluginSettingsPrototype`. |
| 29 | - Plugin model provider overrides belong in plugin `conf/model_providers.yaml` and merge after base `conf/model_providers.yaml`. |
| 30 | - Global and scoped activation are independent and use `.toggle-1` and `.toggle-0`; `always_enabled: true` forces ON and disables UI toggles. |
| 31 | - `hooks.py` runs in the framework runtime. Explicitly target another runtime if a plugin must prepare the agent execution environment. |
| 32 | - `execute.py` is manual user-triggered setup, maintenance, repair, migration, or refresh work; automatic framework behavior belongs in hooks or lifecycle extensions. |
| 33 | - Plugin routes are `GET /plugins/<name>/<path>`, `POST /api/plugins/<name>/<handler>`, and `POST /api/plugins` for management actions. |
| 34 | - `_a0_connector` WebSocket history replay must stay bounded: emit large chat history as paged `connector_context_snapshot` payloads, keep `last_sequence` as the Agent Zero log-output cursor, and avoid sending an entire long transcript in one frame. |
| 35 | - Frontend plugin HTML extensions live under `extensions/webui/<point>/`, include a root Alpine scope, and use `x-move-*` directives when targeting static breakpoints. |
| 36 | - Frontend plugin JS extensions live under `extensions/webui/<point>/` and export a default function. |
| 37 | - Plugin UI must use the A0 notification system for errors, warnings, success, and info instead of inline success/error boxes. |
| 38 | - Bundled plugin WebUI must author Material Symbols as empty `<x-icon name="lowercase_snake_case"></x-icon>` elements and use `:name` for Alpine-driven icon names. Legacy `.material-symbols-outlined` and `.material-icons-outlined` spans remain runtime-compatible for community plugins, but bundled plugins must not introduce new ligature-text spans. |
| 39 | - Banners and discovery cards are provided through Python `banners` extensions by appending dictionaries with unique `id`, `type`, `priority`, and display fields to the `banners` list. |
| 40 | - Alert banner types are `info`, `warning`, and `error`; discovery card types are `hero` and `feature`. |
| 41 | - Banner/card fields may include `title`, `html`, `description`, `thumbnail`, `icon`, `cta_text`, `cta_action`, and `dismissible` depending on type. |
| 42 | - Community discovery cards should use `type: "feature"`; reserve `hero` cards for core system features. |
| 43 | - Supported discovery CTA actions are `open-plugin-config:<plugin_folder_name>`, `open-plugin-hub`, and `open-url:<url>`. |
| 44 | - Plugin deletion or disablement should not leave unmanaged services, symlinks, or files outside plugin-owned paths unless explicitly documented with cleanup. |
| 45 | |
| 46 | ## Work Guidance |
| 47 | |
| 48 | - Prefer plugin-local helpers for behavior used only by one plugin. |
| 49 | - Use shared `helpers/` only for reusable framework behavior. |
| 50 | - Use the notification system for plugin UI feedback. |
| 51 | - Keep plugin README and docs current when user-visible plugin behavior changes. |
| 52 | - Check configuration before injecting setup or discovery banners so configured plugins do not keep advertising setup. |
| 53 | - Use highly unique banner IDs prefixed by plugin name. |
| 54 | - Browser tool prompts must preserve the existing-tab workflow: when a user refers to an already-open URL, tab, or page title, guide agents to `list` and then `set_active` or `navigate` by `browser_id` instead of blindly opening a new tab. |
| 55 | - When preparing community plugins, keep plugin contents at the standalone repository root with `plugin.yaml`, `README.md`, and a root `LICENSE`. |
| 56 | - Plugin Index submissions use a separate `index.yaml` under `a0-plugins/plugins/<name>/`; do not confuse it with runtime `plugin.yaml`. |
| 57 | |
| 58 | ## Verification |
| 59 | |
| 60 | - Run plugin-specific tests after changing a bundled plugin. |
| 61 | - Run framework tests for touched extension points, API handlers, tools, settings, or WebUI surfaces. |
| 62 | - For plugins with external services or browser/desktop integrations, perform a targeted smoke check when practical. |
| 63 | - For banner/discovery changes, verify the Welcome Screen renders alert banners, feature cards, dismiss behavior, priority ordering, and CTA behavior. |
| 64 | |
| 65 | ## Child DOX Index |
| 66 | |
| 67 | Direct child DOX files: |
| 68 | |
| 69 | | Child | Scope | |
| 70 | | --- | --- | |
| 71 | | [_a0_connector/AGENTS.md](_a0_connector/AGENTS.md) | HTTP and WebSocket connector integration with remote tools and runtime bridges. | |
| 72 | | [_agent_editor/AGENTS.md](_agent_editor/AGENTS.md) | Deterministic sparse agent-profile editor API, helpers, and WebUI. | |
| 73 | | [_browser/AGENTS.md](_browser/AGENTS.md) | Playwright browser tool, helpers, viewer, and browser panel UI. | |
| 74 | | [_chat_branching/AGENTS.md](_chat_branching/AGENTS.md) | Chat branching from an existing message. | |
| 75 | | [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. | |
| 76 | | [_chat_naming/AGENTS.md](_chat_naming/AGENTS.md) | Built-in manual and Utility Model-assisted chat naming. | |
| 77 | | [_commands/AGENTS.md](_commands/AGENTS.md) | Built-in slash command manager, command file discovery, and chat composer slash picker. | |
| 78 | | [_context_doctor/AGENTS.md](_context_doctor/AGENTS.md) | Tool-call JSON repair and compact persistence before default dispatch. | |
| 79 | | [_context_window/AGENTS.md](_context_window/AGENTS.md) | Context-window token accounting, API, composer indicator, and visibility control. | |
| 80 | | [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. | |
| 81 | | [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. | |
| 82 | | [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. | |
| 83 | | [_document_query/AGENTS.md](_document_query/AGENTS.md) | Document parsing, indexing, and Q&A tools. | |
| 84 | | [_editor/AGENTS.md](_editor/AGENTS.md) | Native Markdown editor surface and sessions. | |
| 85 | | [_email_integration/AGENTS.md](_email_integration/AGENTS.md) | IMAP/Exchange polling and SMTP reply integration. | |
| 86 | | [_error_retry/AGENTS.md](_error_retry/AGENTS.md) | Critical exception retry lifecycle hooks. | |
| 87 | | [_goal/AGENTS.md](_goal/AGENTS.md) | Built-in chat goal strip, `/goal` slash command, and agent-facing goal tools. | |
| 88 | | [_infection_check/AGENTS.md](_infection_check/AGENTS.md) | Prompt-injection safety analysis before tool execution. | |
| 89 | | [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Kokoro text-to-speech integration. | |
| 90 | | [_memory/AGENTS.md](_memory/AGENTS.md) | Optional persistent recall plugin, knowledge import, tools, and dashboard; do not assume it is enabled outside this plugin. | |
| 91 | | [_migrate_agents/AGENTS.md](_migrate_agents/AGENTS.md) | Built-in migration of chats, projects, memories, instructions, and skills from supported agent harnesses. | |
| 92 | | [_model_config/AGENTS.md](_model_config/AGENTS.md) | Model selection, presets, API-key checks, and scoped overrides. | |
| 93 | | [_oauth/AGENTS.md](_oauth/AGENTS.md) | OAuth-backed model-provider connections and local proxy routes. | |
| 94 | | [_office/AGENTS.md](_office/AGENTS.md) | LibreOffice office artifacts and office canvas sessions. | |
| 95 | | [_onboarding/AGENTS.md](_onboarding/AGENTS.md) | First-time model onboarding wizard. | |
| 96 | | [_orchestrator/AGENTS.md](_orchestrator/AGENTS.md) | External terminal coding-agent orchestration skill, adapter status, and settings UI. | |
| 97 | | [_pin_to_top/AGENTS.md](_pin_to_top/AGENTS.md) | Built-in chat and task sidebar pinning. | |
| 98 | | [_plugin_installer/AGENTS.md](_plugin_installer/AGENTS.md) | Plugin install and update flows from ZIP, Git, and Plugin Index. | |
| 99 | | [_plugin_scan/AGENTS.md](_plugin_scan/AGENTS.md) | LLM-guided security scanner for third-party plugins. | |
| 100 | | [_plugin_validator/AGENTS.md](_plugin_validator/AGENTS.md) | Plugin manifest, structure, convention, and security validator. | |
| 101 | | [_promptinclude/AGENTS.md](_promptinclude/AGENTS.md) | Promptinclude scanning and prompt injection. | |
| 102 | | [_skills/AGENTS.md](_skills/AGENTS.md) | Active and hidden skill configuration and prompt injection. | |
| 103 | | [_telegram_integration/AGENTS.md](_telegram_integration/AGENTS.md) | Telegram bot integration and per-user chat sessions. | |
| 104 | | [_text_editor/AGENTS.md](_text_editor/AGENTS.md) | Native text read, write, and patch tool. | |
| 105 | | [_time_travel/AGENTS.md](_time_travel/AGENTS.md) | Workspace history, diff, travel, snapshot, and revert flows. | |
| 106 | | [_tool_access/AGENTS.md](_tool_access/AGENTS.md) | Always-on project/profile tool-policy execution gate. | |
| 107 | | [_whatsapp_integration/AGENTS.md](_whatsapp_integration/AGENTS.md) | WhatsApp Baileys bridge integration. | |
| 108 | | [_whats_new/AGENTS.md](_whats_new/AGENTS.md) | Version-gated What's New showcase modal, card list, and startup trigger. | |
| 109 | | [_whisper_stt/AGENTS.md](_whisper_stt/AGENTS.md) | Whisper speech-to-text integration. | |