Agent Zero AI framework
Make agent profile overrides presence-aware
Alessandro641df2286818
diff --git a/agents/default/AGENTS.md b/agents/default/AGENTS.mdindex 130d84cc1..956ee7057 100644--- a/agents/default/AGENTS.md+++ b/agents/default/AGENTS.md@@ -8,7 +8,7 @@## Ownership- `agent.yaml` owns default profile metadata.-- `agent.system.main.specifics.md` owns default profile-specific system prompt content.+- `prompts/agent.system.main.specifics.md` owns default profile-specific system prompt content.- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them.## Local Contractsdiff --git a/agents/default/agent.system.main.specifics.md b/agents/default/prompts/agent.system.main.specifics.mdsimilarity index 100%rename from agents/default/agent.system.main.specifics.mdrename to agents/default/prompts/agent.system.main.specifics.mddiff --git a/helpers/subagents.py b/helpers/subagents.pyindex df9d5ae20..e544f4276 100644--- a/helpers/subagents.py+++ b/helpers/subagents.py@@ -28,11 +28,12 @@ class SubAgentListItem(BaseModel):path: str = ""origin: list[Origin] = []enabled: bool = True+ avatar: dict[str, str] | None = None@model_validator(mode="after")def post_validator(self):- if self.title == "":- self.title = self.name+ if "title" not in self.model_fields_set and self.name:+ object.__setattr__(self, "title", self.name)return self@@ -55,7 +56,7 @@ def get_agents_dict(for name, override in overrides.items():base_agent = merged.get(name)merged[name] = (- _merge_agent_list_items(base_agent, override)+ _merge_agent_list_item(base_agent, override)if base_agentelse override)@@ -92,15 +93,15 @@ def _get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentLisfor subdir in subdirs:try:- agent_yaml_path = files.get_abs_path(dir, subdir, "agent.yaml")- if files.exists(agent_yaml_path):- agent_yaml = files.read_file(agent_yaml_path)- agent_data = SubAgentListItem.model_validate(yaml_helper.loads(agent_yaml) or {})- else:- agent_json = files.read_file(files.get_abs_path(dir, subdir, "agent.json"))- agent_data = SubAgentListItem.model_validate_json(agent_json)+ try:+ raw = _read_agent_definition(dir, subdir)+ except FileNotFoundError:+ raw = {}+ agent_data = SubAgentListItem.model_validate(raw)name = agent_data.name or subdiragent_data.name = name+ if "title" not in agent_data.model_fields_set:+ object.__setattr__(agent_data, "title", name)agent_data.path = files.get_abs_path(dir, subdir)agent_data.origin = [origin]result[name] = agent_data@@ -111,15 +112,6 @@ def _get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentLisdef load_agent_data(name: str, project_name: str | None = None) -> SubAgent:- def _merge_agent(- original: SubAgent | None, override: SubAgent | None = None- ) -> SubAgent | None:- if original and override:- return _merge_agents(original, override)- elif original:- return original- return override-from helpers import plugins# load default, plugin, and user agents and merge@@ -184,31 +176,26 @@ def delete_agent_data(name: str) -> None:def _load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None:+ agent_dir = files.get_abs_path(dir, name)+ if not os.path.isdir(agent_dir):+ return None+try:- agent_yaml_path = files.get_abs_path(dir, name, "agent.yaml")- if files.exists(agent_yaml_path):- agent_yaml = files.read_file(agent_yaml_path)- subagent = SubAgent.model_validate(yaml_helper.loads(agent_yaml) or {})- else:- subagent_json = files.read_file(files.get_abs_path(dir, name, "agent.json"))- subagent = SubAgent.model_validate_json(subagent_json)+ subagent = SubAgent.model_validate(_read_agent_definition(dir, name))except Exception:# backward compatibility (before agent.json existed)try:- context_file = files.read_file(files.get_abs_path(dir, name, "_context.md"))+ subagent = SubAgent(+ context=files.read_file(files.get_abs_path(dir, name, "_context.md"))+ )except Exception:- context_file = ""- subagent = SubAgent(- name=name,- title=name,- description="",- context=context_file,- origin=[origin],- prompts={},- )+ subagent = SubAgent()# non-stored fieldssubagent.name = name+ if "title" not in subagent.model_fields_set:+ object.__setattr__(subagent, "title", name)+ subagent.path = agent_dirsubagent.origin = [origin]prompts_dir = f"{dir}/{name}/prompts"@@ -221,37 +208,48 @@ def _load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent |return subagent-def _merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None:+def _read_agent_definition(dir: str, name: str) -> dict:+ yaml_path = files.get_abs_path(dir, name, "agent.yaml")+ if files.exists(yaml_path):+ return yaml_helper.loads(files.read_file(yaml_path)) or {}+ json_path = files.get_abs_path(dir, name, "agent.json")+ if files.exists(json_path):+ return json.loads(files.read_file(json_path)) or {}+ raise FileNotFoundError+++def _merge_agent(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None:if base is None:return overrideif override is None:return base- merged_prompts: dict[str, str] = {}- merged_prompts.update(base.prompts or {})- merged_prompts.update(override.prompts or {})-- return SubAgent(- name=override.name,- title=override.title,- description=override.description,- context=override.context,- origin=_merge_origins(base.origin, override.origin),- prompts=merged_prompts,- )+ data = _merge_agent_metadata(base, override)+ data["prompts"] = {**(base.prompts or {}), **(override.prompts or {})}+ return SubAgent.model_validate(data)-def _merge_agent_list_items(+def _merge_agent_list_item(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem:- return SubAgentListItem(+ return SubAgentListItem.model_validate(_merge_agent_metadata(base, override))+++def _merge_agent_metadata(+ base: SubAgentListItem, override: SubAgentListItem+) -> dict:+ data = base.model_dump()+ data.update(+ override.model_dump(+ exclude_unset=True, exclude={"name", "path", "origin", "prompts"}+ )+ )+ data.update(name=override.name or base.name,- title=override.title or base.title,- description=override.description or base.description,- context=override.context or base.context,path=override.path or base.path,- origin=_merge_origins(base.origin, override.origin),+ origin=[*base.origin, *override.origin],)+ return datadef get_agents_roots() -> list[str]:@@ -296,7 +294,7 @@ def get_all_agents_list() -> list[dict[str, str]]:items = _get_agents_list_from_dir(root, origin=origin)for name, item in items.items():if name in merged:- merged[name] = _merge_agent_list_items(merged[name], item)+ merged[name] = _merge_agent_list_item(merged[name], item)else:merged[name] = item@@ -307,10 +305,6 @@ def get_all_agents_list() -> list[dict[str, str]]:return result-def _merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]:- return base + override--def get_default_promp_file_names() -> list[str]:return files.list_files("prompts", filter="*.md")diff --git a/helpers/subagents.py.dox.md b/helpers/subagents.py.dox.mdindex 9b954ff80..f2aa5a8f1 100644--- a/helpers/subagents.py.dox.md+++ b/helpers/subagents.py.dox.md@@ -14,6 +14,8 @@- `SubAgentListItem` (`BaseModel`)- `post_validator(self)`- `SubAgent` (`SubAgentListItem`)+- Profile metadata includes optional avatar metadata and merges by key presence:+ a missing key inherits, while a present empty value explicitly clears it.- Top-level functions:- `get_agents_list(project_name: str | None=...) -> list[SubAgentListItem]`- `get_agents_dict(project_name: str | None=...) -> dict[str, SubAgentListItem]`@@ -22,11 +24,12 @@- `save_agent_data(name: str, subagent: SubAgent) -> None`- `delete_agent_data(name: str) -> None`- `_load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None`-- `_merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`-- `_merge_agent_list_items(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`+- `_read_agent_definition(dir: str, name: str) -> dict`+- `_merge_agent(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`+- `_merge_agent_list_item(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`+- `_merge_agent_metadata(base: SubAgentListItem, override: SubAgentListItem) -> dict`- `get_agents_roots() -> list[str]`- `get_all_agents_list() -> list[dict[str, str]]`-- `_merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]`- `get_default_promp_file_names() -> list[str]`- `get_available_agents_dict(project_name: str | None) -> dict[str, SubAgentListItem]`- `get_paths(agent: 'Agent|None', *subpaths, must_exist_completely: bool=..., include_project: bool=..., include_user: bool=..., include_default: bool=..., include_plugins: bool=..., default_root: str=...) -> list[str]`: Returns list of file paths for the given agent and subpaths, searched in order of priority:@@ -37,10 +40,15 @@- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence.+- Nonexistent profile layers return `None` instead of synthesizing empty overrides.- Imported dependency areas include: `helpers`, `json`, `os`, `pydantic`, `typing`.## Key Concepts+- Presence-aware merging uses Pydantic's `model_dump(exclude_unset=True)` so+ missing keys inherit while explicitly empty values remain overrides. Runtime+ `name`, `path`, `origin`, and `prompts` fields are handled separately; derived+ title fallbacks do not become authored overrides.- Important called helpers/classes observed in the source: `cache.toggle_area`, `model_validator`, `_get_agents_list_from_dir`, `plugins.get_enabled_plugin_paths`, `_merge_agent_dicts`, `files.get_subdirectories`, `_load_agent_data_from_dir`, `_merge_agent`, `files.write_file`, `files.delete_dir`, `SubAgent`, `SubAgentListItem`, `files.find_existing_paths_by_pattern`, `get_agents_roots`, `files.list_files`, `get_agents_dict`, `cache.determine_cache_key`, `cache.add`, `projects.get_project_meta`, `FileNotFoundError`.- Keep request/response, tool, or helper semantics documented here at the same time as source changes.@@ -55,6 +63,7 @@- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.- Related tests observed by source search:- `tests/test_skills_runtime.py`+ - `tests/test_subagent_metadata_merge.py`## Child DOX Indexdiff --git a/skills/a0-create-agent/SKILL.md b/skills/a0-create-agent/SKILL.mdindex 6d88103c7..36cc663ea 100644--- a/skills/a0-create-agent/SKILL.md+++ b/skills/a0-create-agent/SKILL.md@@ -265,7 +265,7 @@ Profiles inherit all prompts from `/a0/prompts/` and from `/a0/agents/default/`.### The canonical override: `agent.system.main.specifics.md`-This is the designated extension slot for profile-specific role, identity, and behavior instructions. The file ships **empty** in both `/a0/prompts/agent.system.main.specifics.md` and `/a0/agents/default/agent.system.main.specifics.md` precisely so profiles can fill it in without fighting the base prompt. It is included from `agent.system.main.md` right after `agent.system.main.role.md`, so whatever you put here layers on top of the inherited role.+This is the designated extension slot for profile-specific role, identity, and behavior instructions. The file ships **empty** in both `/a0/prompts/agent.system.main.specifics.md` and `/a0/agents/default/prompts/agent.system.main.specifics.md` precisely so profiles can fill it in without fighting the base prompt. It is included from `agent.system.main.md` right after `agent.system.main.role.md`, so whatever you put here layers on top of the inherited role.**Every shipped profile in `/a0/agents/` overrides this file** — a good sanity check that this is the right place for your specialization. Look at the existing profiles for concrete shape:diff --git a/tests/test_subagent_metadata_merge.py b/tests/test_subagent_metadata_merge.pynew file mode 100644index 000000000..7794a55e6--- /dev/null+++ b/tests/test_subagent_metadata_merge.py@@ -0,0 +1,92 @@+from pathlib import Path++from helpers import subagents+++def _write_profile(root: Path, name: str, metadata: str = "") -> Path:+ profile = root / name+ profile.mkdir(parents=True)+ if metadata:+ (profile / "agent.yaml").write_text(metadata, encoding="utf-8")+ return profile+++def test_missing_metadata_inherits_and_present_empty_clears(tmp_path: Path) -> None:+ bundled_root = tmp_path / "agents"+ user_root = tmp_path / "usr-agents"+ _write_profile(+ bundled_root,+ "researcher",+ "title: Researcher\ndescription: Source heavy\ncontext: Delegate research\n",+ )+ _write_profile(user_root, "researcher", "description: ''\ncontext: ''\n")++ bundled = subagents._load_agent_data_from_dir(+ str(bundled_root), "researcher", "default"+ )+ user = subagents._load_agent_data_from_dir(+ str(user_root), "researcher", "user"+ )+ merged = subagents._merge_agent(bundled, user)++ assert merged is not None+ assert merged.title == "Researcher"+ assert merged.description == ""+ assert merged.context == ""+ assert merged.origin == ["default", "user"]+++def test_prompt_only_override_does_not_clear_metadata(tmp_path: Path) -> None:+ bundled_root = tmp_path / "agents"+ user_root = tmp_path / "usr-agents"+ _write_profile(+ bundled_root,+ "researcher",+ "title: Researcher\ndescription: Source heavy\ncontext: Delegate research\n",+ )+ profile = _write_profile(user_root, "researcher")+ prompts = profile / "prompts"+ prompts.mkdir()+ (prompts / "agent.system.main.specifics.md").write_text(+ "Only this changes.\n", encoding="utf-8"+ )++ merged = subagents._merge_agent(+ subagents._load_agent_data_from_dir(+ str(bundled_root), "researcher", "default"+ ),+ subagents._load_agent_data_from_dir(+ str(user_root), "researcher", "user"+ ),+ )++ assert merged is not None+ assert merged.title == "Researcher"+ assert merged.description == "Source heavy"+ assert merged.context == "Delegate research"+ assert merged.prompts == {+ "agent.system.main.specifics.md": "Only this changes.\n"+ }+++def test_nonexistent_layer_is_not_an_override(tmp_path: Path) -> None:+ assert (+ subagents._load_agent_data_from_dir(str(tmp_path), "missing", "user")+ is None+ )+++def test_default_specifics_uses_only_the_canonical_prompt_path() -> None:+ root = Path(__file__).resolve().parents[1]+ legacy = root / "agents" / "default" / "agent.system.main.specifics.md"+ canonical = (+ root+ / "agents"+ / "default"+ / "prompts"+ / "agent.system.main.specifics.md"+ )++ assert not legacy.exists()+ assert canonical.is_file()+ assert canonical.read_bytes() == b""