agent-zero/plugins/AGENTS.md

Plugins DOX

Purpose

• Own bundled system plugins shipped with Agent Zero.
• Provide the tracked plugin architecture contract for both bundled plugins and custom plugins developed under ignored usr/plugins/.
• Keep plugin behavior discoverable, reversible, and compatible across bundled and custom roots without creating DOX files inside usr/.

Ownership

• 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.
• Plugins may also own execute.py, conf/model_providers.yaml, plugin-distributed agents/<profile>/agent.yaml, static assets, and plugin-local docs.
• README.md owns the high-level core plugin architecture summary and community Plugin Index guidance.
• Custom or experimental user plugins belong under usr/plugins/, not here, but this file remains their tracked DOX contract.
• Do not create AGENTS.md files under usr/plugins/ unless the user explicitly asks for ignored user-state documentation.

Local Contracts

• Every plugin directory must include a valid plugin.yaml.
• Runtime manifest fields include name, title, description, version, settings_sections, per_project_config, per_agent_config, and always_enabled.
• Core plugins may use plugins.<plugin_name>... imports when they are shipped from this tree.
• User plugins under usr/plugins/ must use usr.plugins.<plugin_name>... imports and avoid sys.path hacks or persistent symlink-based imports.
• Plugin extension layouts must use extensions/python/<point>/, extensions/python/_functions/<module>/<qualname>/<start|end>/, and extensions/webui/<point>/.
• The _functions extension layout preserves every module and nested qualname segment; do not use retired flattened extension folder names.
• Plugin settings defaults belong in default_config.yaml; runtime user settings belong under usr/.
• Plugin settings resolution order is project/profile, project, user/profile, user plugin config, then bundled default_config.yaml.
• webui/config.html settings UIs must bind plugin values to config.* and modal state/actions to context.* through $store.pluginSettingsPrototype.
• Plugin model provider overrides belong in plugin conf/model_providers.yaml and merge after base conf/model_providers.yaml.
• Global and scoped activation are independent and use .toggle-1 and .toggle-0; always_enabled: true forces ON and disables UI toggles.
• hooks.py runs in the framework runtime. Explicitly target another runtime if a plugin must prepare the agent execution environment.
• execute.py is manual user-triggered setup, maintenance, repair, migration, or refresh work; automatic framework behavior belongs in hooks or lifecycle extensions.
• Plugin routes are GET /plugins/<name>/<path>, POST /api/plugins/<name>/<handler>, and POST /api/plugins for management actions.
• _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.
• Frontend plugin HTML extensions live under extensions/webui/<point>/, include a root Alpine scope, and use x-move-* directives when targeting static breakpoints.
• Frontend plugin JS extensions live under extensions/webui/<point>/ and export a default function.
• Plugin UI must use the A0 notification system for errors, warnings, success, and info instead of inline success/error boxes.
• 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.
• Alert banner types are info, warning, and error; discovery card types are hero and feature.
• Banner/card fields may include title, html, description, thumbnail, icon, cta_text, cta_action, and dismissible depending on type.
• Community discovery cards should use type: "feature"; reserve hero cards for core system features.
• Supported discovery CTA actions are open-plugin-config:<plugin_folder_name>, open-plugin-hub, and open-url:<url>.
• Plugin deletion or disablement should not leave unmanaged services, symlinks, or files outside plugin-owned paths unless explicitly documented with cleanup.

Work Guidance

• Prefer plugin-local helpers for behavior used only by one plugin.
• Use shared helpers/ only for reusable framework behavior.
• Use the notification system for plugin UI feedback.
• Keep plugin README and docs current when user-visible plugin behavior changes.
• Check configuration before injecting setup or discovery banners so configured plugins do not keep advertising setup.
• Use highly unique banner IDs prefixed by plugin name.
• 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.
• When preparing community plugins, keep plugin contents at the standalone repository root with plugin.yaml, README.md, and a root LICENSE.
• Plugin Index submissions use a separate index.yaml under a0-plugins/plugins/<name>/; do not confuse it with runtime plugin.yaml.

Verification

• Run plugin-specific tests after changing a bundled plugin.
• Run framework tests for touched extension points, API handlers, tools, settings, or WebUI surfaces.
• For plugins with external services or browser/desktop integrations, perform a targeted smoke check when practical.
• For banner/discovery changes, verify the Welcome Screen renders alert banners, feature cards, dismiss behavior, priority ordering, and CTA behavior.

Child DOX Index

Direct child DOX files:

Child	Scope
_a0_connector/AGENTS.md	HTTP and WebSocket connector integration with remote tools and runtime bridges.
_browser/AGENTS.md	Playwright browser tool, helpers, viewer, and browser panel UI.
_chat_branching/AGENTS.md	Chat branching from an existing message.
_chat_compaction/AGENTS.md	Full-chat compaction into a summary message.
_code_execution/AGENTS.md	Terminal, Python, and Node.js execution tools and shell runtimes.
_desktop/AGENTS.md	Linux desktop runtime, sessions, and desktop surface.
_discovery/AGENTS.md	Welcome-screen plugin discovery cards and promotions.
_document_query/AGENTS.md	Document parsing, indexing, and Q&A tools.
_editor/AGENTS.md	Native Markdown editor surface and sessions.
_email_integration/AGENTS.md	IMAP/Exchange polling and SMTP reply integration.
_error_retry/AGENTS.md	Critical exception retry lifecycle hooks.
_infection_check/AGENTS.md	Prompt-injection safety analysis before tool execution.
_kokoro_tts/AGENTS.md	Kokoro text-to-speech integration.
_memory/AGENTS.md	Persistent vector memory, knowledge import, tools, and dashboard.
_model_config/AGENTS.md	Model selection, presets, API-key checks, and scoped overrides.
_oauth/AGENTS.md	OAuth-backed model-provider connections and local proxy routes.
_office/AGENTS.md	LibreOffice office artifacts and office canvas sessions.
_onboarding/AGENTS.md	First-time model onboarding wizard.
_plugin_installer/AGENTS.md	Plugin install and update flows from ZIP, Git, and Plugin Index.
_plugin_scan/AGENTS.md	LLM-guided security scanner for third-party plugins.
_plugin_validator/AGENTS.md	Plugin manifest, structure, convention, and security validator.
_promptinclude/AGENTS.md	Promptinclude scanning and prompt injection.
_skills/AGENTS.md	Active and hidden skill configuration and prompt injection.
_telegram_integration/AGENTS.md	Telegram bot integration and per-user chat sessions.
_text_editor/AGENTS.md	Native text read, write, and patch tool.
_time_travel/AGENTS.md	Workspace history, diff, travel, snapshot, and revert flows.
_whatsapp_integration/AGENTS.md	WhatsApp Baileys bridge integration.
_whats_new/AGENTS.md	Version-gated What's New showcase modal and startup trigger.
_whisper_stt/AGENTS.md	Whisper speech-to-text integration.