Agent Zero AI framework
Refactor a0-development into grounded references
Alessandro4b49386f96f7
diff --git a/AGENTS.md b/AGENTS.mdindex 8340f16b9..549f6b559 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -3,8 +3,8 @@[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)+Tech Stack: Framework Python 3.12+ | Agent execution Python 3.13 in Docker | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)+Dev Server: python run_ui.py (discover host/port from startup output or runtime configuration; do not assume a default port)Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)Documentation: README.md | docs/Frontend & Plugin DOX: [WebUI](webui/AGENTS.md) | [Components](webui/components/AGENTS.md) | [Frontend JS](webui/js/AGENTS.md) | [Plugins](plugins/AGENTS.md)@@ -43,22 +43,24 @@ Do not combine these commands; run them individually:pip install -r requirements.txt```- Start WebUI: python run_ui.py+- Discover the WebUI URL from startup output, launcher/Docker port mappings, or explicit `--host`/`--port`/`WEB_UI_PORT` configuration; do not hardcode a default port.---## Docker Environment-When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework from the code being executed:+When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework itself from code executed on behalf of the agent:### 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.+- Purpose: Runs the Agent Zero framework itself: WebUI backend, API, core loop, scheduler, framework imports, and plugin hooks/tools that execute inside the framework process.+- Packages: Contains framework dependencies from requirements.txt.+- Verification: Use this runtime for framework/backend import checks, WebUI startup checks, and plugin hook behavior unless the code explicitly switches environments.-### 2. Execution Runtime (/opt/venv)+### 2. Agent 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.+- Purpose: Default Python environment for the agent's terminal/code-execution tasks and user code run by the agent.+- Behavior: Packages installed by the agent during a task belong here so task dependencies do not pollute or prove the framework runtime. Do not use this runtime as evidence that framework imports, WebUI startup, or plugin hooks work.---diff --git a/skills/a0-development/AGENTS.md b/skills/a0-development/AGENTS.mdindex b53fd4cc0..bfa89616a 100644--- a/skills/a0-development/AGENTS.md+++ b/skills/a0-development/AGENTS.md@@ -3,27 +3,35 @@## Purpose- Own the broad Agent Zero development guide used by agents extending the framework.-- Keep architecture, tools, extensions, API, agents, prompts, projects, and skills guidance in sync with the repository.+- Keep architecture, tools, extensions, API, agents, prompts, projects, plugins, runtime, and skills guidance in sync with the repository.## Ownership-- `SKILL.md` owns the development overview, path conventions, and implementation references.+- `SKILL.md` owns the concise development entry point, routing workflow, path conventions, and reference map.+- `references/` owns detailed source-grounded development references loaded on demand.## Local Contracts- Keep paths and examples current with source files and DOX contracts.- Route plugin-specific tasks to the plugin router or specialist plugin skills.- Do not duplicate long contracts that belong in narrower AGENTS.md files when a reference is enough.+- Reference files must identify current source or DOX anchors and avoid hardcoded default WebUI ports.## Work Guidance- Update this skill after durable framework workflow, extension, tool, API, prompt, or profile changes.- Keep examples operational and compatible with the current helper classes.+- Keep `SKILL.md` lean; move detailed schemas, examples, and topic-specific guidance to `references/`.## Verification-- Manually read `SKILL.md` for stale architecture references and broken related-skill links.+- Manually read `SKILL.md` and changed reference files for stale architecture references, broken relative paths, and specialist-skill duplication.+- Load the skill after reference-map changes and confirm `skills_tool` exposes the expected reference file tree.## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [references/AGENTS.md](references/AGENTS.md) | Source-grounded development references loaded by this skill. |diff --git a/skills/a0-development/SKILL.md b/skills/a0-development/SKILL.mdindex 7dbf21c0e..94d44a500 100644--- a/skills/a0-development/SKILL.md+++ b/skills/a0-development/SKILL.md@@ -1,9 +1,9 @@---name: a0-development-description: Development guide for extending and building features for the Agent Zero AI framework. Covers architecture, tools, extensions, API endpoints, agent profiles, projects, prompts, and skills — with correct paths, imports, and patterns matching the current codebase.-version: 1.0.0+description: Development guide for extending Agent Zero from current source and DOX. Use for framework architecture, tools, extensions, API/WebUI handlers, agent profiles, prompts, skills, projects, runtime boundaries, and contribution workflow. Load the focused reference files before giving implementation guidance.+version: 1.1.0author: Agent Zero Team-tags: ["development", "framework", "agent-zero", "extending", "tools", "extensions", "skills", "api", "agents", "prompts"]+tags: ["development", "framework", "agent-zero", "extending", "tools", "extensions", "skills", "api", "agents", "prompts", "dox"]trigger_patterns:- "extend agent zero"- "agent zero development"@@ -21,826 +21,60 @@ trigger_patterns:- "extension hook points"- "prompt system"- "agent profile"+ - "dox"----# Agent Zero Development Guide+# Agent Zero Development-This skill provides comprehensive, accurate guidance for extending and building features for Agent Zero. Use it when you need to:+Use this skill as the entry point for Agent Zero framework development. It is intentionally lean: load only the reference files that match the task, then verify against the current repository before changing code.-- Understand the **architecture** and project layout-- Create new **Tools** for agent capabilities-- Add **Extensions** to hook into the framework lifecycle-- Build **API Endpoints** for the Web UI-- Create **Agent Profiles** (subordinates) with custom prompts-- Understand and extend the **Prompt System**-- Create **Skills** (see the dedicated `build-skill` skill for the full wizard)-- Work with **Projects** and workspace configuration+## Reality Rules-> **Path convention:** Throughout this guide, `/a0/` refers to the framework root — this is `/a0/` inside Docker, or your local repository root in development. All paths are relative to this root.+1. Source and nearest DOX beat memory, examples, and this skill if they disagree.+2. Before editing, read the applicable `AGENTS.md` chain from the repo root to every file you expect to touch.+3. New capabilities should usually be plugins. For plugin-specific work, load `a0-plugin-router` and follow the routed specialist skill.+4. Do not assume ports. Discover WebUI host/port from startup output, launcher or Docker mapping, or explicit `--host`, `--port`, `WEB_UI_HOST`, and `WEB_UI_PORT` configuration.+5. In Docker, framework checks belong to `/opt/venv-a0` and agent/user code execution belongs to `/opt/venv`. Do not use one runtime as proof for the other.+6. Treat `/a0/` as the runtime framework root inside Docker. In local development it means the repository root. If a live container matters, prove that `/a0` matches the checkout before trusting source-only conclusions.+7. Do not document or change ignored `usr/` or `tmp/` runtime state unless the user explicitly asks.-> [!IMPORTANT]-> **Plugins are the primary way to extend Agent Zero.** Most new tools, extensions, and prompts should be packaged as plugins. For all plugin tasks (create, review, manage, debug, contribute), load the `a0-plugin-router` skill which routes to the appropriate specialist. This guide covers the underlying framework patterns that plugins build upon.+## Reference Map-Related skills: `a0-plugin-router` (plugin tasks) | `build-skill` (skill creation wizard) | `a0-create-plugin` | `a0-review-plugin` | `a0-manage-plugin` | `a0-contribute-plugin` | `a0-debug-plugin`-------## Architecture Overview--### Project Layout--```-/a0/ # Framework root-├── agent.py # Core Agent + AgentContext + AgentConfig classes-├── initialize.py # Agent initialization logic-├── models.py # Model definitions-├── run_ui.py # Web UI entry point-│-├── tools/ # Core tools (search, response, browser, etc.)-├── extensions/-│ ├── python/ # Python lifecycle extensions-│ │ ├── <hook_point>/ # e.g., agent_init/, system_prompt/, etc.-│ │ │ └── _NN_name.py # Numbered extension files-│ │ └── _functions/ # Implicit @extensible decorator extensions-│ └── webui/ # JavaScript WebUI extensions-│ └── <hook_point>/ # e.g., json_api_call_before/-│ └── name.js-├── api/ # Flask API endpoint handlers-├── helpers/ # Framework utilities and base classes-│ ├── tool.py # Tool + Response base classes-│ ├── extension.py # Extension base class + @extensible decorator-│ ├── api.py # ApiHandler base class-│ ├── files.py # File operations + prompt reading-│ ├── plugins.py # Plugin system manager-│ ├── print_style.py # Console output formatting-│ └── ... # Many more utility modules-│-├── prompts/ # Core prompt fragments (system, tools, framework)-├── agents/ # Agent profiles (subordinate specializations)-│ ├── default/ # Base profile (inherited by others)-│ ├── agent0/ # Main user-facing agent-│ ├── developer/ # Developer subordinate-│ ├── hacker/ # Security subordinate-│ ├── researcher/ # Research subordinate-│ └── _example/ # Example profile with tool + extension samples-│-├── plugins/ # Core plugins (tools, extensions, prompts)-│ ├── _code_execution/ # Terminal/Python/Node.js execution-│ ├── _memory/ # Persistent memory system-│ ├── _text_editor/ # File read/write/patch-│ ├── _model_config/ # LLM model selection-│ ├── _infection_check/ # Prompt injection safety-│ └── ... # More core plugins-│-├── skills/ # Core skills (SKILL.md bundles)-├── knowledge/ # Knowledge base files-├── webui/ # Web UI frontend-├── docs/ # Documentation-│-└── usr/ # User-space (survives updates)- ├── agents/ # User-created agent profiles- ├── plugins/ # User-installed plugins- ├── skills/ # User-created skills- ├── knowledge/ # User knowledge base files- ├── extensions/ # Standalone user extensions (created on demand; prefer plugins instead)- ├── projects/ # Project workspaces (created on demand when user adds projects via UI)- └── workdir/ # Default working directory-```--### Key Architecture Patterns--1. **Plugin-first design** — Most capabilities (tools, extensions, prompts) are delivered via plugins in `/a0/plugins/` (core) or `/a0/usr/plugins/` (user).-2. **Extensions execute in numeric order** — Files named `_10_*.py`, `_20_*.py`, etc. run sequentially within each hook point.-3. **Tools inherit from `Tool`** — All tools implement the `execute()` method returning a `Response`.-4. **Shared `AgentContext`** — Enables state persistence across agents in a conversation.-5. **Async/await throughout** — All tool execution, extensions, and API handlers are async.-6. **Prompt fragments compose** — System prompts are assembled from named fragments with includes and variable substitution.-7. **Profile inheritance** — Agent profiles inherit from `default/` and override specific prompt fragments.-8. **User-space separation** — Everything under `/a0/usr/` survives framework updates.--### Agent Loop--The core execution cycle works as follows:--1. **User message** arrives (via UI or API)-2. **System prompt assembly** — prompt fragments are composed with includes and variable substitution-3. **LLM call** — the assembled prompt + conversation history is sent to the model-4. **Response parsing** — the framework parses the LLM response looking for JSON tool calls-5. **Tool execution** — if tool calls are found, each tool's `execute()` method is called and the result is appended to history-6. **Loop continues** — steps 3-5 repeat until the agent produces a `response` tool call (which ends the loop) or a loop limit is reached--Extensions fire at each stage (e.g., `monologue_start`, `before_main_llm_call`, `tool_execute_before`, etc.), allowing plugins to observe and modify behavior at every point.-------## Creating Tools--Tools are how agents interact with the world. Each tool inherits from the `Tool` base class.--### Import Path--```python-from helpers.tool import Tool, Response-```--### Tool Base Class--```python-# /a0/helpers/tool.py--@dataclass-class Response:- message: str # Text response shown to agent- break_loop: bool # True = stop agent message loop- additional: dict[str, Any] | None = None # Extra metadata for history--class Tool:- def __init__(self, agent: Agent, name: str, method: str | None,- args: dict[str,str], message: str,- loop_data: LoopData | None, **kwargs) -> None:- self.agent = agent- self.name = name- self.method = method # For tools with sub-methods (e.g., "skills_tool:load")- self.args = args- self.loop_data = loop_data- self.message = message-- async def execute(self, **kwargs) -> Response:- pass # Override this-- # Lifecycle hooks (called automatically):- async def before_execution(self, **kwargs): ...- async def after_execution(self, response: Response, **kwargs): ...-```--### Where Tools Live--| Location | Purpose |-|---|---|-| `/a0/tools/` | Core framework tools (search, response, call_subordinate, etc.) |-| `/a0/plugins/<plugin>/tools/` | Plugin-provided tools (code_execution, memory, text_editor) |-| `/a0/agents/<profile>/tools/` | Profile-specific tool overrides |-| `/a0/usr/plugins/<plugin>/tools/` | User plugin tools |--### Example: Creating a Tool--Based on the actual `_example` profile in `/a0/agents/_example/tools/example_tool.py`:--```python-# my_tool.py-from helpers.tool import Tool, Response--class MyTool(Tool):- async def execute(self, **kwargs):- # Get arguments — kwargs contains the tool_args from the agent's JSON- input_data = kwargs.get("input", "")-- # Do something- result = f"Processed: {input_data}"-- # Return response- return Response(- message=result, # Shown to the agent- break_loop=False, # Don't stop the agent loop- )-```--> [!IMPORTANT]-> Every tool needs a corresponding **prompt fragment** so the agent knows how to use it. Create a file named `agent.system.tool.<tool_name>.md` in the appropriate `prompts/` directory. See the [Prompt System](#prompt-system) section.--### Tool Best Practices--- Always handle errors gracefully — return error messages in `Response`, don't crash-- Access agent context via `self.agent.context`-- Use `self.method` to support sub-methods (e.g., `my_tool:action1`, `my_tool:action2`)-- Use `kwargs.get()` to read arguments with defaults-- For long operations, use `self.set_progress()` or `self.add_progress()` to show status-- Access `self.loop_data` for loop state (iteration count, timing, etc.) — this is the `LoopData` instance passed during tool dispatch-------## Creating Extensions--Extensions hook into specific lifecycle points in the agent framework.--### Import Path--```python-from helpers.extension import Extension-```--### Extension Base Class--```python-class Extension:- def __init__(self, agent: "Agent | None", **kwargs):- self.agent: "Agent | None" = agent- self.kwargs = kwargs-- def execute(self, **kwargs) -> None | Awaitable[None]:- pass # Override this — kwargs are hook-point-specific-```--> Extensions can be sync or async. If `execute()` returns an `Awaitable`, the framework will `await` it automatically. The `agent` parameter is nullable because some hook points (like `startup_migration` or `banners`) fire before an agent exists.--### Extension File Location--Extensions live in directories named by their hook point. The path structure is:--```-extensions/python/<hook_point>/_NN_name.py-```--Where `_NN_` is a numeric prefix controlling execution order (e.g., `_10_`, `_20_`, `_50_`).--| Source | Path |-|---|---|-| Core extensions | `/a0/extensions/python/<hook_point>/` |-| Plugin extensions | `/a0/plugins/<plugin>/extensions/python/<hook_point>/` |-| User extensions | `/a0/usr/extensions/python/<hook_point>/` |-| Agent profile extensions | `/a0/agents/<profile>/extensions/<hook_point>/` |-| User plugin extensions | `/a0/usr/plugins/<plugin>/extensions/python/<hook_point>/` |--### Python Extension Hook Points--Complete list of available hook points:--| Hook Point | When It Fires | Common Use |-|---|---|---|-| `agent_init` | Agent is initialized | Load configs, set defaults |-| `system_prompt` | System prompt is being assembled | Inject prompt content |-| `monologue_start` | Agent monologue begins | Pre-processing, state setup |-| `message_loop_start` | Before message processing loop | Pre-loop setup |-| `message_loop_prompts_before` | Before prompt assembly in loop | Modify prompt inputs |-| `message_loop_prompts_after` | After prompt assembly in loop | Add context (memory recall lives here) |-| `before_main_llm_call` | Before the LLM API call | Modify prompts, add context |-| `util_model_call_before` | Before utility model calls | Modify utility prompts |-| `response_stream` | When response streaming begins | Initialize stream handlers |-| `response_stream_chunk` | Per response chunk received | Transform output, collect data |-| `response_stream_end` | Response streaming complete | Finalize, analyze full response |-| `reasoning_stream` | Reasoning/thinking stream begins | Monitor reasoning |-| `reasoning_stream_chunk` | Per reasoning chunk | Collect reasoning data |-| `reasoning_stream_end` | Reasoning stream complete | Analyze reasoning |-| `tool_execute_before` | Before a tool runs | Validation, logging, safety checks |-| `tool_execute_after` | After a tool runs | Post-process results |-| `hist_add_before` | Before adding to history | Modify history entries |-| `hist_add_tool_result` | After tool result added to history | Log tool results |-| `message_loop_end` | After message processing loop | Post-loop cleanup |-| `monologue_end` | Agent monologue complete | Memorization, cleanup |-| `process_chain_end` | Entire processing chain done | Final cleanup |-| `job_loop` | Background job loop tick | Periodic background tasks |-| `error_format` | Error is being formatted | Custom error messages |-| `startup_migration` | Framework startup | Data migrations |-| `banners` | Startup banners displayed | Add custom banners |-| `embedding_model_changed` | Embedding model changed | Reload vector stores (fired programmatically, not a directory-based hook) |-| `user_message_ui` | User message from UI | Pre-process user input |-| `webui_ws_connect` | WebSocket client connects | Session setup |-| `webui_ws_disconnect` | WebSocket client disconnects | Session cleanup |-| `webui_ws_event` | WebSocket event received | Handle custom WS events |--### The `@extensible` Decorator (Implicit Extension Points)--Any framework function decorated with `@extensible` automatically gets two extension points:--```-_functions/<module_path>/<qualname_path>/start-_functions/<module_path>/<qualname_path>/end-```--The path mapping converts Python module paths and qualified names using `/` separators:-- Module `agent.py` → `agent`-- Class method `Agent.handle_exception` → `Agent/handle_exception`-- Full path: `_functions/agent/Agent/handle_exception/start`--For nested modules like `helpers.history`, a method `History.add` would map to `_functions/helpers/history/History/add/start`.--For example, a function `Agent.handle_exception` in module `agent` creates:-- `_functions/agent/Agent/handle_exception/start`-- `_functions/agent/Agent/handle_exception/end`--Extensions in these directories receive a `data` dict with:-- `data["args"]` — positional args (mutable)-- `data["kwargs"]` — keyword args (mutable)-- `data["result"]` — set this to short-circuit the function-- `data["exception"]` — set to a `BaseException` to force-raise--This is used by plugins like `_error_retry` to wrap core agent methods.--### WebUI Extensions (JavaScript)--Client-side extensions live under `extensions/webui/<hook_point>/`:--| Hook Point | When It Fires |-|---|---|-| `json_api_call_before` | Before a JSON API request |-| `json_api_call_after` | After a JSON API response |-| `fetch_api_call_before` | Before a fetch API request |-| `fetch_api_call_after` | After a fetch API response |-| `get_message_handler` | Register custom message renderers |-| `set_messages_before_loop` | Before messages are rendered |-| `set_messages_after_loop` | After messages are rendered |-| `webui_ws_push` | WebSocket push to client |--### Example: Creating an Extension--Based on the actual `_example` profile in `/a0/agents/_example/extensions/agent_init/_10_example_extension.py`:--```python-# extensions/python/agent_init/_15_my_extension.py-from helpers.extension import Extension--class MyExtension(Extension):- async def execute(self, **kwargs):- # Access the agent- agent = self.agent- context = agent.context-- # Extension logic — kwargs content depends on the hook point- agent.agent_name = "CustomAgent" + str(agent.number)-```--### Extension Execution Order--Extensions execute in numeric order based on filename prefix:--```-_10_first.py # Runs first-_20_second.py # Runs second-_50_third.py # Runs third-```--Use 10-number increments to leave room for future extensions.-------## Creating API Endpoints--API endpoints serve the Web UI and external clients using Flask.--### Import Path--```python-from helpers.api import ApiHandler-from flask import Request, Response-```--### ApiHandler Base Class--```python-class ApiHandler:- def __init__(self, app: Flask, thread_lock: ThreadLockType):- self.app = app- self.thread_lock = thread_lock-- # Override these class methods to configure behavior:- @classmethod- def requires_loopback(cls) -> bool: return False # Restrict to localhost- @classmethod- def requires_api_key(cls) -> bool: return False # Require API key- @classmethod- def requires_auth(cls) -> bool: return True # Require auth session- @classmethod- def get_methods(cls) -> list[str]: return ["POST"] # HTTP methods- @classmethod- def requires_csrf(cls) -> bool: return cls.requires_auth() # CSRF protection-- # Implement this:- async def process(self, input: dict, request: Request) -> dict | Response:- pass-- # Utility: get or create an agent context- def use_context(self, ctxid: str, create_if_not_exists: bool = True) -> AgentContext:- ...-```--### Where API Endpoints Live--| Location | Purpose |-|---|---|-| `/a0/api/` | Core API endpoints |-| `/a0/plugins/<plugin>/api/` | Plugin API endpoints |-| `/a0/usr/plugins/<plugin>/api/` | User plugin API endpoints |--Endpoints are auto-discovered by filename. The route is derived from the filename (e.g., `my_endpoint.py` -> `/api/my_endpoint`).--### Example: API Endpoint--```python-# api/my_endpoint.py-from helpers.api import ApiHandler-from flask import Request, Response-from agent import AgentContext--class MyEndpoint(ApiHandler):- @classmethod- def get_methods(cls) -> list[str]:- return ["GET", "POST"]-- async def process(self, input: dict, request: Request) -> dict:- param = input.get("param", "default")-- # Get or create agent context- ctxid = input.get("context", "")- context = self.use_context(ctxid)-- return {- "result": f"processed {param}",- "context": context.id,- }-```-------## Creating Agent Profiles--Agent profiles define specialized subordinates with custom prompts and behaviors.--> For a guided, step-by-step wizard (scope selection, `agent.yaml` schema, prompt overrides, tool/extension stubs, test checklist) use the dedicated `/a0/skills/a0-create-agent/SKILL.md` skill.--### Profile Directory Structure--```-agents/<profile-name>/-+-- agent.yaml # Required: profile metadata-+-- prompts/ # Optional: prompt overrides-| +-- agent.system.main.role.md # Role definition (most common override)-| +-- agent.system.main.communication.md # Communication style-| +-- agent.system.tool.<name>.md # Tool-specific prompts-+-- tools/ # Optional: profile-specific tools-| +-- my_tool.py-+-- extensions/ # Optional: profile-specific extensions- +-- <hook_point>/- +-- _NN_extension.py-```--### agent.yaml Format--The actual format is simple YAML with only three fields:--```yaml-title: Developer-description: Agent specialized in complex software development.-context: Use this agent for software development tasks, including writing code,- debugging, refactoring, and architectural design.-```--| Field | Purpose |-|---|---|-| `title` | Display name shown in UI and agent selection |-| `description` | Brief description of the agent's specialization |-| `context` | Instructions for when to delegate to this profile |--> [!NOTE]-> There is **no** model configuration, temperature, or allowed_tools in the profile YAML. `agent.yaml` contains only `title`, `description`, and `context`. Profile-specific Main/Utility model settings are managed by the `_model_config` plugin in `usr/agents/<profile>/plugins/_model_config/config.json`. Tool availability is controlled by plugin activation.--### Where Profiles Live--| Location | Purpose |-|---|---|-| `/a0/agents/` | Core profiles (default, agent0, developer, hacker, researcher) |-| `/a0/usr/agents/` | User-created profiles (survives updates) |--### Prompt Override Mechanism--Profiles inherit all prompts from the `default/` profile. To customize behavior, place prompt files with the **same name** in your profile's `prompts/` directory. The framework searches profile-specific prompts first, then falls back to the default.--The most common override is `agent.system.main.role.md` which defines the agent's role and specialization.--### Example: Creating a Profile--```yaml-# /a0/usr/agents/data-analyst/agent.yaml-title: Data Analyst-description: Agent specialized in data analysis, visualization, and statistical modeling.-context: Use this agent for data analysis tasks, creating visualizations, statistical- analysis, and working with datasets in Python.-```--```markdown-<!-- /a0/usr/agents/data-analyst/prompts/agent.system.main.role.md -->--## Your role-You are a specialized data analysis agent.-Your expertise includes:-- Python data analysis (pandas, numpy, scipy)-- Data visualization (matplotlib, seaborn, plotly)-- Statistical modeling and hypothesis testing-- SQL queries and database analysis-- Data cleaning and preprocessing--## Process-1. Understand the data and the question-2. Choose appropriate tools and methods-3. Execute analysis with code_execution_tool-4. Visualize results when applicable-5. Provide clear interpretation of findings-```--### Reference: The `_example` Profile--The framework includes a complete example profile at `/a0/agents/_example/` that demonstrates:-- Custom tool: `/a0/agents/_example/tools/example_tool.py`-- Custom extension: `/a0/agents/_example/extensions/agent_init/_10_example_extension.py`-- Tool prompt: `/a0/agents/_example/prompts/agent.system.tool.example_tool.md`-- Role prompt: `/a0/agents/_example/prompts/agent.system.main.role.md`-------## Prompt System--Agent Zero assembles system prompts from **named fragments** using includes and variable substitution.--### Prompt File Naming Convention--Prompt files follow a dot-separated naming scheme:--```-agent.system.main.md # Main system prompt (entry point)-agent.system.main.role.md # Role definition-agent.system.main.communication.md # Communication style-agent.system.tool.<name>.md # Tool usage instructions-agent.system.tools.md # Tools overview-agent.system.projects.main.md # Project system-agent.system.secrets.md # Secret handling-agent.system.skills.md # Skills listing-agent.system.datetime.md # Current date/time-agent.context.extras.md # Context extras-fw.*.md # Framework messages (errors, hints, etc.)-```--### Where Prompts Live--| Location | Priority | Purpose |-|---|---|---|-| `/a0/agents/<profile>/prompts/` | Highest | Profile-specific overrides |-| `/a0/usr/agents/<profile>/prompts/` | High | User profile overrides |-| `/a0/plugins/<plugin>/prompts/` | Normal | Plugin-provided prompts |-| `/a0/usr/plugins/<plugin>/prompts/` | Normal | User plugin prompts |-| `/a0/prompts/` | Base | Core framework prompts |--The framework searches directories in priority order and uses the **first match** found.--### Include Mechanism--Prompts can include other fragments using double-brace `include` directives.--The syntax uses opening double-brace, the keyword, and closing double-brace:--| Directive | Purpose |-|---|---|-| `{{include "agent.system.main.role.md"}}` | Include a named prompt fragment |-| `{{include "agent.system.main.communication.md"}}` | Include another fragment |-| `{{include original}}` | Include the same file from the next lower-priority directory |--The `include original` directive is particularly useful for **extending** rather than fully **replacing** a prompt — your override can include the base version and add to it.--### Variable Substitution--Prompts support `{{variable_name}}` placeholders that are replaced at render time with values passed from the framework or plugin configuration.--### Conditional Blocks--Prompts support conditional rendering based on variables.--### Reading Prompts in Code--```python-# From within an Agent method:-content = self.read_prompt("fw.some_message.md", variable1="value1")--# From helpers:-from helpers.files import read_prompt_file-content = read_prompt_file("template.md", _directories=[...], var="value")-```-------## Creating Skills--Skills are reusable instruction bundles that the agent loads on demand via the `skills_tool`. Each skill lives in a directory containing a `SKILL.md` file with YAML frontmatter.--| Location | Purpose |-|---|---|-| `/a0/skills/` | Core skills (shipped with framework) |-| `/a0/usr/skills/` | User-created skills (survives updates) |--The agent interacts with skills through JSON tool calls:--```json-{"tool_name": "skills_tool:list", "tool_args": {}}-{"tool_name": "skills_tool:load", "tool_args": {"skill_name": "my-skill"}}-```--> For the complete skill creation wizard — including SKILL.md format, frontmatter fields, directory structure, best practices, and examples — load the `build-skill` skill.-------## Working with Projects--Projects provide isolated workspaces with custom configuration.--> Projects are typically created and managed via the Web UI. The `.a0proj/` directory and `project.json` are auto-generated when you create a project through the UI.--### Project Structure--```-/a0/usr/projects/<project-name>/-+-- .a0proj/-| +-- project.json # Project configuration-| +-- agents.json # Per-project agent overrides-| +-- variables.env # Non-sensitive variables-| +-- secrets.env # Encrypted secrets-| +-- memory/ # Project-specific memory-| +-- index.faiss-| +-- index.pkl-| +-- embedding.json-+-- <project-files>/ # Your project files (working directory)-```--### project.json Format+Load references with:```json-{- "title": "My Project",- "description": "Project description",- "instructions": "Markdown instructions for the agent when this project is active",- "color": "#3a86ff",- "git_url": "",- "memory": "own",- "file_structure": {- "enabled": true,- "max_depth": 5,- "max_files": 20,- "max_folders": 20,- "max_lines": 250,- "gitignore": ".a0proj/\nvenv/\n**/__pycache__/\n**/node_modules/\n**/.git/\n"- }-}+{"tool_name": "skills_tool:read_file", "tool_args": {"skill_name": "a0-development", "file_path": "references/<file>.md"}}```-| Field | Purpose |-|---|---|-| `title` | Display name |-| `description` | Brief description |-| `instructions` | Markdown injected into agent system prompt when project is active |-| `color` | UI accent color (hex) |-| `git_url` | Optional Git repository URL |-| `memory` | `"own"` for project-specific memory, or shared |-| `file_structure` | Controls the working directory tree shown to the agent |-------## Plugin System Overview--Plugins are the **primary extension mechanism** in Agent Zero. A plugin can bundle tools, extensions, prompts, API endpoints, helpers, and UI components into a self-contained package.--> For all plugin tasks — creating, reviewing, managing, contributing, or debugging plugins — load the `a0-plugin-router` skill, which routes to the appropriate specialist skill.--### Core Plugins--The framework ships with these core plugins in `/a0/plugins/`:--| Plugin | Purpose |-|---|---|-| `_code_execution` | Terminal, Python, Node.js code execution |-| `_memory` | Persistent vector memory system |-| `_text_editor` | File read/write/patch with line numbers |-| `_model_config` | LLM model selection and configuration |-| `_browser` | Direct browser automation and WebUI viewing |-| `_infection_check` | Prompt injection safety checks |-| `_error_retry` | Retry on critical exceptions |-| `_email_integration` | Email communication via IMAP/SMTP |-| `_telegram_integration` | Telegram bot integration |-| `_chat_branching` | Branch chats from any message |-| `_promptinclude` | Persistent behavioral rules (*.promptinclude.md) |-| `_plugin_installer` | Install plugins from ZIP/Git/Hub |-| `_plugin_scan` | Security scanning for plugins |-| `_plugin_validator` | Plugin manifest and code validation |-------## Common Patterns Reference--### Accessing Agent Context--```python-# Shared across all agents in a conversation-context = self.agent.context-data = context.data # dict-like shared state--# Store data-data["my_key"] = my_value--# Retrieve data-value = data.get("my_key", default)-```--### Using File Helpers--```python-from helpers import files--# File operations-content = files.read_file("path/to/file")-files.write_file("path/to/file", content)-exists = files.exists("path/to/file")--# Read and render a prompt file-content = files.read_prompt_file("template.md", _directories=[...], var="value")-```--### Console Output--```python-from helpers.print_style import PrintStyle--PrintStyle.hint("Informational message")-PrintStyle.warning("Warning message")-PrintStyle.error("Error message")-PrintStyle(font_color="#85C1E9").print("Custom styled output")-```--### Error Handling--```python-from helpers.tool import Response--try:- result = await risky_operation()-except Exception as e:- PrintStyle.error(f"Operation failed: {e}")- return Response(message=f"Error: {e}", break_loop=False)-```-------## Development Workflow--When building features for Agent Zero:--### 1. Choose Your Extension Point--| Want to... | Use |-|---|---|-| Add a new agent capability | **Tool** (in a plugin) |-| Hook into agent lifecycle | **Extension** (in a plugin) |-| Add Web UI functionality | **API endpoint** + **WebUI extension** |-| Create a specialized agent | **Agent profile** |-| Bundle reusable instructions | **Skill** |-| Package everything together | **Plugin** (recommended) |--### 2. Develop in User Space--- New plugins -> `/a0/usr/plugins/<name>/`-- New profiles -> `/a0/usr/agents/<name>/`-- New skills -> `/a0/usr/skills/<name>/`-- New extensions -> `/a0/usr/extensions/python/<hook_point>/`--### 3. Test and Iterate--- **Local dev**: Run `python run_ui.py` (default port 50001 at `http://localhost:50001`)-- **Docker**: Restart the container or use the UI restart button; check logs with `docker logs -f <container_name>`-- Test with minimal input first-- Verify in the Web UI--### 4. Contributing--For contribution guidelines, see `/a0/docs/contribution.md`. For plugin contributions to the community Plugin Index, load the `a0-contribute-plugin` skill.-------## Best Practices--### DO-- Use the **plugin system** for new features (see `a0-create-plugin` skill)-- Follow existing code patterns and conventions-- Write clear docstrings and comments-- Handle errors gracefully in tools and extensions-- Create prompt fragments for every tool (`agent.system.tool.<name>.md`)-- Develop in `/a0/usr/` directories to survive updates-- Test with the `_example` profile as a reference-- Use `from helpers.*` imports (not `from python.helpers.*`)--### DON'T-- Modify files in `/a0/plugins/` or `/a0/tools/` directly (use usr/ space)-- Hardcode paths or configuration values-- Skip creating prompt files for tools-- Ignore the plugin system (it's the intended extension mechanism)-- Mix sync and async code carelessly-- Access internal structures when helpers exist-------## Quick Reference: Key Files--| File | Purpose |+| Need | Read ||---|---|-| `/a0/agent.py` | Core `Agent`, `AgentContext`, `AgentConfig` classes |-| `/a0/helpers/tool.py` | `Tool` + `Response` base classes |-| `/a0/helpers/extension.py` | `Extension` base + `@extensible` decorator |-| `/a0/helpers/api.py` | `ApiHandler` base class |-| `/a0/helpers/files.py` | File ops + prompt reading |-| `/a0/helpers/plugins.py` | Plugin system manager |-| `/a0/helpers/print_style.py` | Console output formatting |-| `/a0/agents/_example/` | Reference example profile with tool + extension |-| `/a0/prompts/agent.system.main.md` | Main system prompt entry point |+| Runtime split, root layout, discovery order, path and port boundaries | `references/architecture-runtime.md` |+| DOX edit workflow, when to update docs, file-level DOX checks | `references/dox-workflow.md` |+| Tool contracts, locations, prompts, and verification | `references/tools.md` |+| Python/WebUI extension discovery, hook points, ordering, implicit hooks | `references/extensions.md` |+| HTTP API, WebSocket handlers, WebUI extension surfaces | `references/api-webui.md` |+| Agent profiles, prompts, skills, projects | `references/agents-prompts-skills-projects.md` |+| Plugin-first workflow, where to put new work, handoffs to plugin skills | `references/plugins-workflow.md` |++## Working Flow++1. Classify the request: tool, extension, API/WebUI, profile, prompt, skill, project, plugin, runtime, or docs.+2. Read the root `AGENTS.md`, then the nearest child `AGENTS.md` files for the target paths.+3. Read the focused reference file from this skill.+4. Inspect the current source files named by the reference before making a claim or patch.+5. Keep changes narrow and in the repo-owned surface. Prefer `usr/` for user-created runtime content, but do not document ignored user state unless requested.+6. Update DOX when a durable contract, path, behavior, workflow, responsibility, or verification rule changes.+7. Run targeted checks from the relevant DOX file. For skill-only changes, at minimum verify frontmatter parsing, reference paths, and markdown sanity.++## Handoffs++- Plugin creation: load `a0-create-plugin`.+- Plugin management or installation: load `a0-manage-plugin`.+- Plugin debugging: load `a0-debug-plugin`.+- Plugin review or publishing: load `a0-review-plugin` or `a0-contribute-plugin`.+- Agent profile creation: load `a0-create-agent`.+- Skill creation or skill format work: load `build-skill`.++## Closeout++Report the exact files changed, the grounding checks used, whether DOX was updated or intentionally left unchanged, and what verification ran. If a claim depends on a live Docker runtime, include the runtime proof, not only checkout evidence.diff --git a/skills/a0-development/references/AGENTS.md b/skills/a0-development/references/AGENTS.mdnew file mode 100644index 000000000..0b913600c--- /dev/null+++ b/skills/a0-development/references/AGENTS.md@@ -0,0 +1,38 @@+# A0 Development References DOX++## Purpose++- Own focused reference files loaded by the `a0-development` skill on demand.+- Keep detailed framework-development guidance grounded in current source files and nearest DOX contracts.++## Ownership++- `architecture-runtime.md` owns runtime, path, discovery-order, and port-boundary guidance.+- `dox-workflow.md` owns the edit and closeout workflow for DOX-governed changes.+- `tools.md` owns core and plugin tool development contracts.+- `extensions.md` owns backend and frontend extension contracts.+- `api-webui.md` owns HTTP API, WebSocket, and WebUI extension guidance.+- `agents-prompts-skills-projects.md` owns profiles, prompt fragments, skills, and project metadata guidance.+- `plugins-workflow.md` owns plugin-first placement and handoff guidance.++## Local Contracts++- Every reference file must list source anchors or DOX anchors that can be checked in the repository.+- Prefer pointing to narrower `AGENTS.md` files instead of copying long subtree contracts.+- Keep examples minimal and compatible with the current helper classes.+- Do not include hardcoded default WebUI ports or environment-specific credentials.++## Work Guidance++- Update the focused reference file when source or DOX changes make its guidance stale.+- If a reference starts duplicating a specialist skill, shorten it and hand off to that skill instead.+- Treat checked-in examples as examples, not authority, when they conflict with current discovery code.++## Verification++- Manually read changed references for broken relative paths, stale source anchors, and duplicated specialist-skill material.+- After changing reference names, load `a0-development` and confirm the file tree exposes the new paths through `skills_tool`.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-development/references/agents-prompts-skills-projects.md b/skills/a0-development/references/agents-prompts-skills-projects.mdnew file mode 100644index 000000000..27f5eac17--- /dev/null+++ b/skills/a0-development/references/agents-prompts-skills-projects.md@@ -0,0 +1,95 @@+# Agents, Prompts, Skills, And Projects++## Source Anchors++- Agent profiles: `/a0/helpers/subagents.py`, `/a0/agents/AGENTS.md`+- Prompt rendering: `/a0/agent.py`, `/a0/helpers/files.py`, `/a0/prompts/AGENTS.md`+- Skill runtime: `/a0/helpers/skills.py`, `/a0/tools/skills_tool.py`, `/a0/skills/AGENTS.md`+- Project metadata: `/a0/helpers/projects.py`, `/a0/api/projects.py`, `/a0/webui/components/projects/`++## Agent Profiles++Bundled profiles live under `agents/<profile>/`. User-created profiles live under `usr/agents/<profile>/`. Plugin-distributed profiles live under plugin `agents/` directories.++The current profile loader accepts `agent.yaml` or `agent.json` and validates through `helpers.subagents.SubAgentListItem` / `SubAgent` fields:++| Field | Meaning |+|---|---|+| `title` | Human-readable display name. Defaults to profile name if empty. |+| `description` | Brief specialization. |+| `context` | Delegation guidance for when to use the profile. |+| `enabled` | Optional availability flag in list contexts. |++Bundled `agent.yaml` files currently use `title`, `description`, and `context`. Model settings are not read from `agent.yaml`; the `_model_config` plugin owns model configuration and scoped overrides.++Profile folders may contain `prompts/`, `tools/`, `extensions/`, and `skills/`, but verify discovery code before relying on example layout. Source and DOX beat stale examples.++## Prompt System++Agents render prompt fragments through `Agent.read_prompt(...)`, which calls `helpers.files.read_prompt_file(...)`.++Prompt capabilities:++- Placeholder replacement with `{{variable_name}}`.+- Conditional blocks with `{{if ...}} ... {{endif}}`.+- Include directives such as `{{include "file.md"}}`.+- `{{include original}}` to include the same file from a lower-priority directory.++Prompt locations include:++| Location | Use |+|---|---|+| `prompts/` | Core framework prompts. |+| `agents/<profile>/prompts/` | Bundled profile overrides. |+| `usr/agents/<profile>/prompts/` | User profile overrides. |+| `plugins/<plugin>/prompts/` | Bundled plugin prompt additions or overrides. |+| `usr/plugins/<plugin>/prompts/` | User plugin prompts. |++Prompt changes can change agent behavior. Keep edits narrow and run targeted prompt, budget, snapshot, tool, or behavior tests.++## Skills++Skills are directories containing `SKILL.md` frontmatter plus optional `references/`, `scripts/`, or `assets/`.++Skill roots come from `helpers.skills.get_skill_roots(...)`, including bundled skills, user skills, project metadata, profile skills, and plugin skills.++`skills_tool` actions:++| Action | Purpose |+|---|---|+| `list` | List available skills without full content. |+| `search` | Search skill metadata and triggers. |+| `load` | Load `SKILL.md` body and show the skill file tree. |+| `read_file` | Read a file inside the skill directory, such as `references/foo.md`. |++Keep always-loaded `SKILL.md` concise. Move long examples, schemas, policies, and variant-specific details into one-level-deep `references/` files and tell the agent when to read them.++Use `build-skill` for skill creation and skill format work.++## Projects++Projects live under `usr/projects/<name>/` and store metadata in `.a0proj/`.++Important project files and folders:++| Path | Purpose |+|---|---|+| `.a0proj/project.json` | Project title, description, instructions, color, git URL, include-AGENTS option, and file-structure settings. |+| `.a0proj/instructions/` | Additional text instruction files. |+| `.a0proj/knowledge/` | Project knowledge files. |+| `.a0proj/variables.env` | Non-sensitive project variables. |+| `.a0proj/secrets.env` | Encrypted project secrets. |+| `.a0proj/agents/` | Per-project agent profile material. |+| `.a0proj/skills/` | Project-scoped skills. |+| `.a0proj/mcp_servers.json` | Project MCP server configuration. |++`helpers.projects.BasicProjectData` currently normalizes `title`, `description`, `instructions`, `include_agents_md`, `color`, `git_url`, and `file_structure`. `EditProjectData` adds runtime/editing fields such as `variables`, `secrets`, `mcp_servers`, `subagents`, and git status.++Project file-structure injection uses settings for `enabled`, `max_depth`, `max_files`, `max_folders`, `max_lines`, and `gitignore`.++## Verification++- Run profile-loading tests when changing agent profile schema or discovery.+- Inspect rendered prompts when changing prompt filenames, include behavior, placeholders, or prompt order.+- Run skill runtime/catalog tests after changing skill loading, search, active/hidden behavior, or skill format.+- For project changes, test create/load/edit paths and project prompt injection when relevant.diff --git a/skills/a0-development/references/api-webui.md b/skills/a0-development/references/api-webui.mdnew file mode 100644index 000000000..7ee2e4cd6--- /dev/null+++ b/skills/a0-development/references/api-webui.md@@ -0,0 +1,93 @@+# API And WebUI++## Source Anchors++- HTTP handler base and route registration: `/a0/helpers/api.py`+- API DOX: `/a0/api/AGENTS.md`+- WebSocket handler base: `/a0/helpers/ws.py`+- WebUI shell DOX: `/a0/webui/AGENTS.md`+- Component and JS DOX: `/a0/webui/components/AGENTS.md`, `/a0/webui/js/AGENTS.md`+- Frontend extension loading: `/a0/webui/js/extensions.js`++## HTTP API Contract++HTTP API handlers derive from `helpers.api.ApiHandler`:++```python+from flask import Request, Response+from helpers.api import ApiHandler++class MyEndpoint(ApiHandler):+ @classmethod+ def get_methods(cls) -> list[str]:+ return ["POST"]++ async def process(self, input: dict, request: Request) -> dict | Response:+ return {"ok": True}+```++Defaults from `ApiHandler`:++| Method | Default |+|---|---|+| `requires_loopback()` | `False` |+| `requires_api_key()` | `False` |+| `requires_auth()` | `True` |+| `get_methods()` | `["POST"]` |+| `requires_csrf()` | `requires_auth()` |++Override these only when the endpoint contract requires it. Keep auth and CSRF protection intact for browser-facing state changes.++## API Routes++`helpers.api.register_api_route(...)` registers:++```text+/api/<path:path>+```++Resolution:++- Built-in endpoint `api/<name>.py` becomes `/api/<name>`.+- Plugin endpoint `plugins/<plugin>/api/<handler>.py` becomes `/api/plugins/<plugin>/<handler>`.++Return a Flask `Response` for files, redirects, custom status codes, and plain text. Return a dictionary for JSON success payloads.++Direct files under `api/*.py` require matching `api/*.py.dox.md`.++## WebSocket Handlers++WebSocket handlers live in `api/ws_*.py` or plugin API folders and derive from `helpers.ws.WsHandler`:++```python+from helpers.ws import WsHandler++class MyHandler(WsHandler):+ async def process(self, event: str, data: dict, sid: str) -> dict | None:+ return {"ok": True}+```++`WsHandler` mirrors `ApiHandler` security flags: auth defaults to `True`, CSRF defaults to auth, API-key and loopback default to `False`. Handlers should validate event data before using it and avoid returning secrets or unfiltered exception details.++## WebUI Work++Follow the nearest WebUI DOX before changing frontend files:++- `webui/AGENTS.md` for the shell, CSS, assets, vendor, and extension loader.+- `webui/js/AGENTS.md` for stores, modals, API helpers, and JS infrastructure.+- `webui/components/AGENTS.md` and child docs for Alpine components.++Patterns:++- Store-dependent content should be gated by a `template x-if` guard before using `$store.<name>`.+- Stores are registered with `createStore` from `/js/AlpineStore.js`.+- Modals use `openModal(path)` and `closeModal()` from `/js/modals.js`.+- Plugin settings UIs bind persisted plugin values to `config.*` and modal-only state/actions to `context.*`.+- Plugin UI should use the A0 notification system instead of inline success/error boxes.++## Verification++- Run endpoint-specific tests or nearest API/WebSocket tests for handler behavior.+- For auth, CSRF, upload/download, tunnel, or file endpoints, run security-focused regressions.+- For WebUI changes, use targeted component/store tests or a browser smoke check when practical.+- Check file-level DOX coverage when touching direct `api/*.py` modules.diff --git a/skills/a0-development/references/architecture-runtime.md b/skills/a0-development/references/architecture-runtime.mdnew file mode 100644index 000000000..97e7b09cd--- /dev/null+++ b/skills/a0-development/references/architecture-runtime.md@@ -0,0 +1,79 @@+# Architecture And Runtime++## Source Anchors++- Root contract: `/a0/AGENTS.md`+- WebUI entry point: `/a0/run_ui.py`+- Runtime arguments and WebUI port resolution: `/a0/helpers/runtime.py`+- Docker Python runtimes: `/a0/docker/base/fs/ins/install_python.sh`+- Docker framework activation: `/a0/docker/run/fs/ins/setup_venv.sh`+- Docker UI launch manager: `/a0/docker/run/fs/exe/self_update_manager.py`+- Search/discovery roots: `/a0/helpers/subagents.py`, `/a0/helpers/skills.py`, `/a0/helpers/projects.py`++## Runtime Split++Agent Zero has two Docker Python runtimes:++| Runtime | Python | Purpose |+|---|---|---|+| `/opt/venv-a0` | 3.12.4 | Framework runtime. Runs the WebUI backend, API, scheduler, agent loop, framework imports, plugin hooks, and framework-side tools. |+| `/opt/venv` | 3.13 | Agent execution runtime. Use for Python code executed on behalf of the agent or user task dependencies. |++Use `/opt/venv-a0` for framework import checks, WebUI startup checks, API/plugin hook behavior, and `py_compile` of framework code inside Docker. Use `/opt/venv` only when the feature explicitly targets agent/user code execution.++Do not claim a package works in the framework because it imports in `/opt/venv`, and do not claim user-code execution works because it imports in `/opt/venv-a0`.++## Ports And URLs++Do not hardcode a WebUI default port in guidance. Discover the effective URL from:++- WebUI startup output.+- Launcher or Docker published-port mapping.+- Explicit `--host` and `--port` arguments.+- `WEB_UI_HOST` and `WEB_UI_PORT` environment configuration.+- Live container inspection when the task targets a running runtime.++`helpers.runtime.get_web_ui_port()` has a code fallback, and the Docker UI manager passes an internal container port. Those are implementation details, not a stable user-facing URL contract.++## Root Paths++- `/a0/` means the framework root inside the Docker runtime.+- In a local checkout, `/a0/` in documentation maps to the repository root.+- `usr/` contains user state, projects, settings, skills, plugins, chats, and workdirs.+- `tmp/` contains runtime caches and generated working files.+- Do not document ignored `usr/` or `tmp/` changes unless explicitly asked.++When the user names a live Dockerized runtime, the live `/a0` tree is a separate artifact. Verify the file sync or runtime state directly before treating checkout code as live behavior.++## Project Layout++Key root areas:++| Path | Purpose |+|---|---|+| `agent.py` | `Agent`, `AgentContext`, `AgentConfig`, prompt reading, tool loop. |+| `initialize.py` | Framework initialization and background loop startup. |+| `models.py` | Model provider and LiteLLM transport configuration. |+| `run_ui.py` | Flask/Socket.IO ASGI WebUI startup. |+| `api/` | HTTP API handlers and `ws_*.py` WebSocket handlers. |+| `helpers/` | Shared framework utilities and base contracts. |+| `tools/` | Core tool implementations. |+| `extensions/` | Built-in backend and WebUI extension points. |+| `plugins/` | Bundled system plugins. |+| `agents/` | Bundled agent profiles. |+| `prompts/` | Core prompt fragments. |+| `skills/` | Bundled skills. |+| `webui/` | Alpine.js frontend shell, components, CSS, assets, and vendor code. |++## Discovery Order++Agent-specific path resolution is handled by `helpers.subagents.get_paths(...)`. In broad terms, project and user/profile paths have higher priority than plugin and bundled defaults, then user root/plugin roots, then base defaults. Inspect `helpers/subagents.py` for exact order before changing discovery behavior.++Skill discovery is handled by `helpers.skills.get_skill_roots(...)`. Skills may come from bundled `skills/`, user `usr/skills/`, project metadata, agent profile folders, and plugin roots. Loaded skills can expose additional files via `skills_tool action=read_file`.++## Development Bias++- Prefer plugins for new capabilities.+- Prefer `helpers/` only for reusable framework behavior.+- Prefer small, source-backed changes over broad rewrites.+- If an example conflicts with source discovery code or DOX, treat the example as stale until verified.diff --git a/skills/a0-development/references/dox-workflow.md b/skills/a0-development/references/dox-workflow.mdnew file mode 100644index 000000000..8623fd468--- /dev/null+++ b/skills/a0-development/references/dox-workflow.md@@ -0,0 +1,66 @@+# DOX Workflow++## Source Anchors++- Root DOX contract: `/a0/AGENTS.md`+- Skill parent contract: `/a0/skills/AGENTS.md`+- Local skill contract: `/a0/skills/a0-development/AGENTS.md`+- Reference-file contract: `/a0/skills/a0-development/references/AGENTS.md`+- File-level DOX examples: `/a0/api/*.py.dox.md`, `/a0/tools/*.py.dox.md`, `/a0/helpers/*.py.dox.md`++## Before Editing++1. Read the root `AGENTS.md`.+2. Identify every path you expect to touch.+3. Walk from the root to each target path.+4. Read every `AGENTS.md` found on that route.+5. If a parent `AGENTS.md` lists a child whose scope contains the path, read that child and continue.+6. Use the nearest `AGENTS.md` as the local contract. Parent docs still apply.+7. If docs conflict, the closer doc controls local details, but no child weakens DOX.++Do not rely on memory for DOX. Re-read the current files.++## When To Update DOX++Update the nearest owning `AGENTS.md` when a meaningful change affects:++- Purpose, ownership, responsibilities, or scope.+- Durable structure, directories, file contracts, or child indexes.+- Runtime behavior, required inputs/outputs, side effects, or verification rules.+- User or agent workflow rules.+- Creation, deletion, rename, or movement of an `AGENTS.md` file.++Update parent docs when parent-level structure or child indexes change. Remove stale or contradictory text rather than explaining old history.++Small implementation edits that do not change contracts may leave DOX unchanged, but still perform the DOX closeout pass and say why docs stayed unchanged.++Do not create or update DOX under ignored `usr/` or `tmp/` unless explicitly requested.++## File-Level DOX++Some directories require per-file `.dox.md` companions:++| Directory | Requirement |+|---|---|+| `api/` | Every direct `*.py` endpoint or `ws_*.py` module must have matching `*.py.dox.md`. |+| `tools/` | Every direct `*.py` tool module must have matching `*.py.dox.md`. |+| `helpers/` | Many helper modules use file-level DOX; follow `helpers/AGENTS.md` before changing helper behavior. |++When adding, deleting, renaming, or behaviorally changing one of those files, update the companion DOX in the same change.++## Closeout++1. Re-check changed paths against the DOX chain.+2. Update nearest owning docs and affected parents or children.+3. Refresh affected Child DOX Index tables.+4. Remove stale or contradictory text.+5. Run relevant verification from the nearest DOX.+6. Report docs intentionally left unchanged and why.++## Practical Verification++- `git diff --check` for whitespace.+- Targeted tests named by the relevant DOX file.+- Manual read-through for skill/reference link changes.+- Shell coverage checks for file-level DOX when touching `api/` or `tools/`.+- Runtime or live-container proof when the user asks about the running Dockerized system.diff --git a/skills/a0-development/references/extensions.md b/skills/a0-development/references/extensions.mdnew file mode 100644index 000000000..c04112089--- /dev/null+++ b/skills/a0-development/references/extensions.md@@ -0,0 +1,150 @@+# Extensions++## Source Anchors++- Extension base and discovery: `/a0/helpers/extension.py`+- Backend extension DOX: `/a0/extensions/AGENTS.md`, `/a0/extensions/python/AGENTS.md`+- WebUI extension DOX: `/a0/extensions/webui/AGENTS.md`+- Plugin extension contract: `/a0/plugins/AGENTS.md`+- Example profile note: `/a0/agents/_example/AGENTS.md`++## Python Extension Contract++Backend extensions derive from `helpers.extension.Extension`:++```python+from helpers.extension import Extension++class MyExtension(Extension):+ async def execute(self, **kwargs):+ ...+```++`self.agent` may be `None` for startup or non-agent hooks. Match the arguments supplied by the hook point. Keep imports light because many extensions run in hot paths.++## Python Discovery Layout++`helpers.extension._get_extension_classes(...)` discovers backend extension classes through:++```text+extensions/python/<extension_point>/+```++using `helpers.subagents.get_paths(agent, "extensions/python", extension_point)`.++Common locations:++| Location | Use |+|---|---|+| `extensions/python/<point>/` | Built-in framework extension. |+| `plugins/<plugin>/extensions/python/<point>/` | Bundled plugin extension. |+| `usr/plugins/<plugin>/extensions/python/<point>/` | User plugin extension. |+| `usr/extensions/python/<point>/` | Standalone user extension. Prefer plugin packaging for durable features. |+| Project/profile roots resolved by `helpers.subagents.get_paths(...)` | Scope-specific extension overrides when discovery supports the path. Verify before copying examples. |++The checked-in `_example` profile contains an older-looking `agents/_example/extensions/agent_init/...` sample. Current discovery code expects `extensions/python/<point>`. Treat source code and DOX as authority before copying profile extension layout.++## Ordering And Overrides++- Files are sorted by filename. Numeric prefixes like `_10_`, `_20_`, `_50_` control order.+- Use gaps between prefixes so future extensions can fit between them.+- Discovery de-duplicates by module filename, preserving the first occurrence by search priority.+- Do not bypass secret masking, auth, persistence, or cleanup extensions for convenience.++## Implicit `@extensible` Hooks++Functions decorated with `@extensible` emit two implicit hook points:++```text+_functions/<module>/<qualname>/start+_functions/<module>/<qualname>/end+```++The path preserves every module segment and nested qualname segment. Example:++```text+helpers.something.Outer.Inner.__init__+```++becomes:++```text+_functions/helpers/something/Outer/Inner/__init__/start+_functions/helpers/something/Outer/Inner/__init__/end+```++Extensions receive a mutable `data` dict with `args`, `kwargs`, `result`, and `exception`. They may mutate inputs, short-circuit by setting `result`, or force/clear an exception.++Do not use retired flattened `_functions` folder names.++## Current Built-In Python Hook Directories++Directory-backed built-in hook points currently include:++```text+agent_init+banners+before_main_llm_call+error_format+hist_add_before+hist_add_tool_result+job_loop+message_loop_end+message_loop_prompts_after+message_loop_prompts_before+message_loop_start+monologue_end+monologue_start+process_chain_end+reasoning_stream+reasoning_stream_chunk+reasoning_stream_end+response_stream+response_stream_chunk+response_stream_end+startup_migration+system_prompt+tool_execute_after+tool_execute_before+user_message_ui+util_model_call_before+webui_ws_connect+webui_ws_disconnect+webui_ws_event+```++This list comes from the current `extensions/python/` tree. Re-check the tree before claiming the complete current set.++## WebUI Extension Points++Frontend extension files live under:++```text+extensions/webui/<point>/+plugins/<plugin>/extensions/webui/<point>/+usr/plugins/<plugin>/extensions/webui/<point>/+```++Current built-in WebUI extension directories include:++```text+fetch_api_call_after+fetch_api_call_before+get_message_handler+initFw_end+json_api_call_after+json_api_call_before+right-canvas-panels+right_canvas_register_surfaces+set_messages_after_loop+set_messages_before_loop+webui_ws_push+```++Plugin frontend HTML extensions should include a root Alpine scope and use `x-move-*` directives when targeting static breakpoints. JS extensions export a default function.++## Verification++- Run targeted lifecycle, prompt, stream, WebSocket, or WebUI extension tests for changed hook points.+- Smoke-test startup for `agent_init`, `startup_migration`, and `system_prompt` changes when practical.+- Check the exact directory path used by `helpers.extension` before adding profile or plugin extension files.diff --git a/skills/a0-development/references/plugins-workflow.md b/skills/a0-development/references/plugins-workflow.mdnew file mode 100644index 000000000..39c94f393--- /dev/null+++ b/skills/a0-development/references/plugins-workflow.md@@ -0,0 +1,91 @@+# Plugins And Development Workflow++## Source Anchors++- Plugin contract: `/a0/plugins/AGENTS.md`+- Plugin helper code: `/a0/helpers/plugins.py`+- Plugin specialist skills: `/a0/skills/a0-plugin-router/SKILL.md`, `/a0/skills/a0-create-plugin/SKILL.md`, `/a0/skills/a0-debug-plugin/SKILL.md`, `/a0/skills/a0-review-plugin/SKILL.md`+- Root development contract: `/a0/AGENTS.md`++## Plugin-First Rule++Plugins are the primary way to extend Agent Zero. A plugin can bundle:++- `plugin.yaml`+- `default_config.yaml`+- `hooks.py`+- `execute.py`+- `tools/`+- `api/`+- `helpers/`+- `prompts/`+- `skills/`+- `extensions/python/`+- `extensions/webui/`+- `webui/`+- plugin-local docs and assets++Use root framework directories only when changing bundled framework behavior itself. For custom or experimental work, use `usr/plugins/<plugin>/` unless the task is explicitly to change a bundled plugin.++## Imports And Runtime++- Bundled plugins under `plugins/` may use `plugins.<plugin_name>...` imports.+- User plugins under `usr/plugins/` should use `usr.plugins.<plugin_name>...` imports.+- Avoid `sys.path` hacks and symlink-dependent imports.+- `hooks.py` runs inside the framework runtime (`/opt/venv-a0` in Docker).+- If a plugin must prepare the agent execution runtime or system packages, it must explicitly target that environment in a subprocess.++## Manifest And Configuration++Every plugin needs `plugin.yaml`. Runtime fields include:++- `name`+- `title`+- `description`+- `version`+- `settings_sections`+- `per_project_config`+- `per_agent_config`+- `always_enabled`++Defaults belong in `default_config.yaml`. Runtime user settings belong under `usr/`.++Settings resolution order is project/profile, project, user/profile, user plugin config, then bundled `default_config.yaml`.++## Activation And Cleanup++- Global and scoped activation are independent.+- Activation files use `.toggle-1` for ON and `.toggle-0` for OFF.+- `always_enabled: true` forces ON and disables UI toggles.+- Plugin deletion or disablement should not leave unmanaged services, symlinks, or files outside plugin-owned paths unless explicitly documented with cleanup.++## Routes And UI++Plugin routes:++| Route | Purpose |+|---|---|+| `GET /plugins/<name>/<path>` | Static/plugin web assets. |+| `POST /api/plugins/<name>/<handler>` | Plugin API handler. |+| `POST /api/plugins` | Plugin management actions. |++Plugin settings UIs should bind saved values to `config.*` and modal-only state/actions to `context.*` through `$store.pluginSettingsPrototype`.++Plugin UI errors, warnings, success, and info should use the A0 notification system.++## Workflow++1. Decide whether the request is plugin-specific. If yes, load `a0-plugin-router`.+2. If creating a plugin, load `a0-create-plugin`.+3. If debugging a plugin, load `a0-debug-plugin`.+4. If reviewing or publishing a plugin, load `a0-review-plugin` or `a0-contribute-plugin`.+5. Read `plugins/AGENTS.md` and any plugin-local `AGENTS.md`.+6. Keep changes inside the plugin boundary unless shared framework behavior truly belongs in `helpers/` or root code.+7. Update plugin docs/DOX when user-visible behavior, configuration, routes, hooks, or cleanup changes.++## Verification++- Run plugin-specific tests after changing a bundled plugin.+- Run framework tests for touched tools, API handlers, extension points, settings, or WebUI surfaces.+- Smoke-test external-service, browser, desktop, or connector integrations when practical.+- For discovery banners/cards, verify rendering, dismiss behavior, ordering, and CTA behavior.diff --git a/skills/a0-development/references/tools.md b/skills/a0-development/references/tools.mdnew file mode 100644index 000000000..632b53416--- /dev/null+++ b/skills/a0-development/references/tools.md@@ -0,0 +1,76 @@+# Tools++## Source Anchors++- Tool base class: `/a0/helpers/tool.py`+- Core tool contract: `/a0/tools/AGENTS.md`+- Tool dispatch path: `/a0/agent.py`+- Skills tool reference-file behavior: `/a0/tools/skills_tool.py`+- Example profile tool: `/a0/agents/_example/tools/example_tool.py`+- Prompt fragments: `/a0/prompts/AGENTS.md`++## Contract++All tools derive from `helpers.tool.Tool` and implement:++```python+from helpers.tool import Tool, Response++class MyTool(Tool):+ async def execute(self, **kwargs) -> Response:+ return Response(message="done", break_loop=False)+```++`Response` fields:++| Field | Meaning |+|---|---|+| `message` | Text appended as the tool result and shown back to the agent. |+| `break_loop` | `True` stops the current message loop. |+| `additional` | Optional metadata added with the tool result. |++`Tool` instances receive `agent`, `name`, `method`, `args`, `message`, and `loop_data`. Use `self.method` for method-style tools such as `skills_tool:load`.++## Locations++| Location | Use |+|---|---|+| `tools/` | Core framework tools. Use only for bundled framework behavior. |+| `plugins/<plugin>/tools/` | Bundled plugin tools. |+| `usr/plugins/<plugin>/tools/` | User plugin tools. This is the preferred place for custom plugin work. |+| `agents/<profile>/tools/` | Profile-local tools. Verify current discovery before relying on profile examples. |++Most new tools should be packaged in a plugin, not added directly to root `tools/`.++## Prompt Contract++Every tool needs an agent-facing prompt fragment so the model knows the tool name, JSON shape, arguments, and when to use it.++Common locations:++- Core tool prompt: `prompts/agent.system.tool.<tool_name>.md`+- Plugin tool prompt: `plugins/<plugin>/prompts/agent.system.tool.<tool_name>.md`+- User plugin prompt: `usr/plugins/<plugin>/prompts/agent.system.tool.<tool_name>.md`+- Profile override prompt: `agents/<profile>/prompts/agent.system.tool.<tool_name>.md`++When changing a tool name, argument shape, output behavior, safety rule, or `break_loop` behavior, update its prompt and tests together.++## Progress And Interventions++- Use `await self.set_progress(...)` when progress should be visible through the tool-output update extension.+- `self.add_progress(...)` only accumulates local progress text.+- For long-running or external-result workflows, follow `tools/AGENTS.md` and use `await self.agent.handle_intervention(...)` where pause/intervention flow matters.+- Sanitize and mask secrets before logging or returning outputs.++## Core Tool DOX++Direct files under `tools/*.py` require matching `tools/*.py.dox.md`. The companion file owns purpose, arguments, output, `break_loop`, side effects, prompt contract notes, dependencies, and verification.++Plugin tool documentation belongs in that plugin's docs or DOX contract, not in root `tools/`.++## Verification++- Run targeted tests for changed tools.+- Run prompt/snapshot tests when tool instructions or output shape changes.+- For direct root tools, verify every `tools/*.py` has a matching `.py.dox.md`.+- If the tool is plugin-scoped, also run plugin-specific checks from the plugin's `AGENTS.md`.