Agent Zero AI framework
refactor: migrate extension system to use deep directory paths based on module and qualname
frdel7e1d9ad2a4a3
diff --git a/docs/developer/extensions.md b/docs/developer/extensions.mdindex a140c107a..22a8c6f45 100644--- a/docs/developer/extensions.md+++ b/docs/developer/extensions.md@@ -77,7 +77,24 @@ The system prompt is built by multiple focused extensions in `extensions/python/| `_13_secrets_prompt.py` | Secrets and variables | `@extensible` || `_14_project_prompt.py` | Project context | `@extensible` |-Each extension exposes a top-level `build_prompt(agent)` function decorated with `@extensible`, which auto-creates `_start` and `_end` hooks. Plugins can hook into these to modify the prompt before or after it's built.+Each extension exposes a top-level `build_prompt(agent)` function decorated with `@extensible`, which auto-creates implicit `start` and `end` extension folders. Plugins can hook into these to modify the prompt before or after it's built.++The implicit path is composed from the function's full module path and full nested `__qualname__` path:++- `_functions/<module path>/<qualname path>/start`+- `_functions/<module path>/<qualname path>/end`++For example, a top-level function `build_prompt` in module `extensions.python.system_prompt._10_main_prompt` maps to:++- `extensions/python/_functions/extensions/python/system_prompt/_10_main_prompt/build_prompt/start/`+- `extensions/python/_functions/extensions/python/system_prompt/_10_main_prompt/build_prompt/end/`++For nested callables, every namespace-like segment is kept. For example, `helpers.something -> Outer.Inner.__init__` maps to:++- `_functions/helpers/something/Outer/Inner/__init__/start`+- `_functions/helpers/something/Outer/Inner/__init__/end`++This deep directory structure avoids collisions between functions that previously would have been flattened into the same extension point name.Numbers `_10`–`_14` run before plugin extensions (which start at `_15`+), ensuring core prompt sections are built first.diff --git a/extensions/python/__main___init_a0_end/_10_register_watchdogs.py b/extensions/python/_functions/__main__/init_a0/end/_10_register_watchdogs.pysimilarity index 100%rename from extensions/python/__main___init_a0_end/_10_register_watchdogs.pyrename to extensions/python/_functions/__main__/init_a0/end/_10_register_watchdogs.pydiff --git a/extensions/python/agent_Agent_handle_exception_end/_40_handle_intervention_exception.py b/extensions/python/_functions/agent/Agent/handle_exception/end/_40_handle_intervention_exception.pysimilarity index 100%rename from extensions/python/agent_Agent_handle_exception_end/_40_handle_intervention_exception.pyrename to extensions/python/_functions/agent/Agent/handle_exception/end/_40_handle_intervention_exception.pydiff --git a/extensions/python/agent_Agent_handle_exception_end/_50_handle_repairable_exception.py b/extensions/python/_functions/agent/Agent/handle_exception/end/_50_handle_repairable_exception.pysimilarity index 100%rename from extensions/python/agent_Agent_handle_exception_end/_50_handle_repairable_exception.pyrename to extensions/python/_functions/agent/Agent/handle_exception/end/_50_handle_repairable_exception.pydiff --git a/extensions/python/agent_Agent_handle_exception_end/_90_handle_critical_exception.py b/extensions/python/_functions/agent/Agent/handle_exception/end/_90_handle_critical_exception.pysimilarity index 100%rename from extensions/python/agent_Agent_handle_exception_end/_90_handle_critical_exception.pyrename to extensions/python/_functions/agent/Agent/handle_exception/end/_90_handle_critical_exception.pydiff --git a/extensions/python/startup_migration/.gitkeep b/extensions/python/startup_migration/.gitkeepnew file mode 100644index 000000000..e69de29bbdiff --git a/helpers/backup.py b/helpers/backup.pyindex b38c9f005..a2b9d6781 100644--- a/helpers/backup.py+++ b/helpers/backup.py@@ -7,7 +7,6 @@ import platformfrom typing import List, Dict, Any, Optionalfrom pathspec import PathSpec-from pathspec.patterns.gitwildmatch import GitWildMatchPatternfrom helpers import files, runtime, gitfrom helpers.print_style import PrintStyle@@ -262,7 +261,7 @@ class BackupService:processed_count = 0try:- spec = PathSpec.from_lines(GitWildMatchPattern, pattern_lines)+ spec = PathSpec.from_lines("gitignore", pattern_lines)# Walk through base directoriesfor base_pattern_path, base_real_path in self.base_paths.items():@@ -508,8 +507,7 @@ class BackupService:if pattern_lines:from pathspec import PathSpec- from pathspec.patterns.gitwildmatch import GitWildMatchPattern- restore_spec = PathSpec.from_lines(GitWildMatchPattern, pattern_lines)+ restore_spec = PathSpec.from_lines("gitignore", pattern_lines)# Process each file in archivefor archive_path in archive_files:@@ -665,8 +663,7 @@ class BackupService:if pattern_lines:from pathspec import PathSpec- from pathspec.patterns.gitwildmatch import GitWildMatchPattern- restore_spec = PathSpec.from_lines(GitWildMatchPattern, pattern_lines)+ restore_spec = PathSpec.from_lines("gitignore", pattern_lines)# Process each file in archivefor archive_path in archive_files:diff --git a/helpers/extension.py b/helpers/extension.pyindex cfcbf8286..4948a5576 100644--- a/helpers/extension.py+++ b/helpers/extension.py@@ -52,10 +52,25 @@ def _log_extension_call(name: str):def extensible(func):"""Make a function emit two implicit extension points around its execution.- The decorator derives two extension point names from the wrapped function:+ The decorator derives two extension point folder paths from the wrapped+ function:- - ``{func.__module__}_{func.__qualname__}_start`` with `.` replaced by `_`- - ``{func.__module__}_{func.__qualname__}_end`` with `.` replaced by `_`+ - ``_functions/<module path>/<qualname path>/start``+ - ``_functions/<module path>/<qualname path>/end``++ Module path segments come from ``func.__module__`` split by ``.``.+ Qualname path segments come from the full nested ``func.__qualname__`` split+ by ``.``, excluding ``<locals>``.++ Example:++ - module ``helpers.something``+ - qualname ``Outer.Inner.__init__``++ becomes:++ - ``_functions/helpers/something/Outer/Inner/__init__/start``+ - ``_functions/helpers/something/Outer/Inner/__init__/end``When the wrapped function is called, the decorator builds a mutable ``data``payload and passes it to both extension points:@@ -72,11 +87,11 @@ def extensible(func):Behavior:- - ``-start`` extensions run first and may mutate inputs or set+ - ``start`` extensions run first and may mutate inputs or set``data["result"]`` / ``data["exception"]``.- If ``data["result"]`` is still unset, the decorator calls the wrappedfunction using the possibly modified ``data["args"]`` / ``data["kwargs"]``.- - ``-end`` extensions run last and may rewrite ``data["result"]`` or replace /+ - ``end`` extensions run last and may rewrite ``data["result"]`` or replace /clear ``data["exception"]``.Finally, if ``data["exception"]`` contains an exception it is raised;@@ -97,13 +112,19 @@ def extensible(func):return Nonedef _prepare_inputs(args, kwargs):- module_name = getattr(func, "__module__", "").replace(".", "_")- qual_name = getattr(func, "__qualname__", "").replace(".", "_")+ module_name = getattr(func, "__module__", "")+ qual_name = getattr(func, "__qualname__", "")if not module_name or not qual_name:return None- start_point = f"{module_name}_{qual_name}_start"- end_point = f"{module_name}_{qual_name}_end"+ module_parts = [part for part in module_name.split(".") if part]+ qual_parts = [part for part in qual_name.split(".") if part and part != "<locals>"]+ if not module_parts or not qual_parts:+ return None++ base_path = os.path.join("_functions", *module_parts, *qual_parts)+ start_point = os.path.join(base_path, "start")+ end_point = os.path.join(base_path, "end")agent = _get_agent(args, kwargs)diff --git a/helpers/file_tree.py b/helpers/file_tree.pyindex b08361e60..acc1101d1 100644--- a/helpers/file_tree.py+++ b/helpers/file_tree.py@@ -502,7 +502,7 @@ def _resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optionalif not lines:return None- return PathSpec.from_lines("gitwildmatch", lines)+ return PathSpec.from_lines("gitignore", lines)def _list_directory_children(diff --git a/helpers/migration.py b/helpers/migration.pyindex 477bb51d0..caa09892a 100644--- a/helpers/migration.py+++ b/helpers/migration.py@@ -1,7 +1,7 @@import osimport jsonfrom helpers import files-from helpers import subagents+from helpers import subagents, extensionfrom helpers import yaml as yaml_helperfrom helpers.print_style import PrintStyle@@ -10,6 +10,10 @@ def startup_migration() -> None:migrate_user_data()convert_agents_json_yaml()+ extension.call_extensions_sync("startup_migration", None)+++def migrate_user_data() -> None:"""Migrate user data from /tmp and other locations to /usr.diff --git a/plugins/_email_integration/helpers/imap_client.py b/plugins/_email_integration/helpers/imap_client.pyindex 7d3db8cf1..58107e22d 100644--- a/plugins/_email_integration/helpers/imap_client.py+++ b/plugins/_email_integration/helpers/imap_client.py@@ -390,7 +390,7 @@ def _html_to_text(html_content: str, cid_map: dict[str, str] | None = None) -> sif cid_map:soup = BeautifulSoup(html_content, "html.parser")for img in soup.find_all("img"):- src = str(img.get("src", ""))+ src = str(img.get("src", "")) # type: ignoreif src.startswith("cid:"):cid = src[4:]if cid in cid_map:diff --git a/plugins/_error_retry/extensions/python/agent_Agent_handle_exception_end/_80_retry_critical_exception.py b/plugins/_error_retry/extensions/python/_functions/agent/Agent/handle_exception/end/_80_retry_critical_exception.pysimilarity index 92%rename from plugins/_error_retry/extensions/python/agent_Agent_handle_exception_end/_80_retry_critical_exception.pyrename to plugins/_error_retry/extensions/python/_functions/agent/Agent/handle_exception/end/_80_retry_critical_exception.pyindex 6e01d551e..222a9f74d 100644--- a/plugins/_error_retry/extensions/python/agent_Agent_handle_exception_end/_80_retry_critical_exception.py+++ b/plugins/_error_retry/extensions/python/_functions/agent/Agent/handle_exception/end/_80_retry_critical_exception.py@@ -7,7 +7,7 @@ from helpers.errors import RepairableException, HandledExceptionfrom helpers import errorsfrom helpers.print_style import PrintStyle-from plugins._error_retry.extensions.python.agent_Agent_monologue_start._10_reset_critical_exception_counter import DATA_NAME_COUNTER+from plugins._error_retry.extensions.python._functions.agent.Agent.monologue.start._10_reset_critical_exception_counter import DATA_NAME_COUNTERclass RetryCriticalException(Extension):async def execute(self, data: dict = {}, **kwargs):diff --git a/plugins/_error_retry/extensions/python/agent_Agent_monologue_start/_10_reset_critical_exception_counter.py b/plugins/_error_retry/extensions/python/_functions/agent/Agent/monologue/start/_10_reset_critical_exception_counter.pysimilarity index 100%rename from plugins/_error_retry/extensions/python/agent_Agent_monologue_start/_10_reset_critical_exception_counter.pyrename to plugins/_error_retry/extensions/python/_functions/agent/Agent/monologue/start/_10_reset_critical_exception_counter.pydiff --git a/plugins/_model_config/extensions/python/agent_Agent_get_browser_model_start/_10_model_config.py b/plugins/_model_config/extensions/python/_functions/agent/Agent/get_browser_model/start/_10_model_config.pysimilarity index 100%rename from plugins/_model_config/extensions/python/agent_Agent_get_browser_model_start/_10_model_config.pyrename to plugins/_model_config/extensions/python/_functions/agent/Agent/get_browser_model/start/_10_model_config.pydiff --git a/plugins/_model_config/extensions/python/agent_Agent_get_chat_model_start/_10_model_config.py b/plugins/_model_config/extensions/python/_functions/agent/Agent/get_chat_model/start/_10_model_config.pysimilarity index 100%rename from plugins/_model_config/extensions/python/agent_Agent_get_chat_model_start/_10_model_config.pyrename to plugins/_model_config/extensions/python/_functions/agent/Agent/get_chat_model/start/_10_model_config.pydiff --git a/plugins/_model_config/extensions/python/agent_Agent_get_embedding_model_start/_10_model_config.py b/plugins/_model_config/extensions/python/_functions/agent/Agent/get_embedding_model/start/_10_model_config.pysimilarity index 100%rename from plugins/_model_config/extensions/python/agent_Agent_get_embedding_model_start/_10_model_config.pyrename to plugins/_model_config/extensions/python/_functions/agent/Agent/get_embedding_model/start/_10_model_config.pydiff --git a/plugins/_model_config/extensions/python/agent_Agent_get_utility_model_start/_10_model_config.py b/plugins/_model_config/extensions/python/_functions/agent/Agent/get_utility_model/start/_10_model_config.pysimilarity index 100%rename from plugins/_model_config/extensions/python/agent_Agent_get_utility_model_start/_10_model_config.pyrename to plugins/_model_config/extensions/python/_functions/agent/Agent/get_utility_model/start/_10_model_config.pydiff --git a/plugins/_model_config/extensions/python/initialize_migration_start/_10_migrate_model_config.py b/plugins/_model_config/extensions/python/startup_migration/_10_migrate_model_config.pysimilarity index 99%rename from plugins/_model_config/extensions/python/initialize_migration_start/_10_migrate_model_config.pyrename to plugins/_model_config/extensions/python/startup_migration/_10_migrate_model_config.pyindex 58d525da7..952c3a908 100644--- a/plugins/_model_config/extensions/python/initialize_migration_start/_10_migrate_model_config.py+++ b/plugins/_model_config/extensions/python/startup_migration/_10_migrate_model_config.py@@ -28,7 +28,7 @@ class MigrateModelConfig(Extension):"browser_model_rl_output", "browser_model_kwargs", "browser_http_headers",]- async def execute(self, **kwargs):+ def execute(self, **kwargs):# Check if global plugin config already existsglobal_config_path = files.get_abs_path("plugins/_model_config/config.json")if os.path.exists(global_config_path):diff --git a/plugins/_promptinclude/helpers/scanner.py b/plugins/_promptinclude/helpers/scanner.pyindex 9adb83a2d..1dfb8a8b7 100644--- a/plugins/_promptinclude/helpers/scanner.py+++ b/plugins/_promptinclude/helpers/scanner.py@@ -131,7 +131,7 @@ def _build_ignore_spec(gitignore: str) -> PathSpec | None:]if not lines:return None- return PathSpec.from_lines("gitwildmatch", lines)+ return PathSpec.from_lines("gitignore", lines)def _find_matching_files(