Agent Zero AI framework
refactor: consolidate module loading utilities and add plugin lifecycle improvements
frdel89d4b8913f40
diff --git a/docs/agents/AGENTS.plugins.md b/docs/agents/AGENTS.plugins.mdindex a5a1851a4..aa01f7ee8 100644--- a/docs/agents/AGENTS.plugins.md+++ b/docs/agents/AGENTS.plugins.md@@ -116,12 +116,14 @@ Design guidance:Plugins can include an optional `hooks.py` file at the plugin root. Agent Zero loads this module on demand and calls exported functions by name through `helpers.plugins.call_plugin_hook(...)`.- `hooks.py` runs inside the **Agent Zero framework runtime and Python environment**, not the separate agent execution environment.-- Use it for framework-internal operations such as install-time setup, plugin registration work, filesystem preparation, cache updates, or other tasks that need access to Agent Zero internals.+- Use it for framework-internal operations such as install-time setup, pre-update cleanup or preparation, plugin registration work, filesystem preparation, cache updates, or other tasks that need access to Agent Zero internals.- Hook functions may be synchronous or async. Async hooks are awaited by the framework.- Hook modules are cached until plugin caches are cleared, so changes may require a plugin refresh/reload cycle.- Plugin hooks should be cleanup-safe. A plugin should not leave behind permanent system modifications, symlinks, files outside its owned paths, or background services that survive plugin removal unless that behavior is explicitly part of the user-facing contract.-Current example: the plugin installer calls `install()` from `hooks.py` after a plugin is copied into place.+Current built-in usage:+- the plugin installer calls `install()` from `hooks.py` after a plugin is copied into place+- the plugin updater calls `pre_update()` from `hooks.py` immediately before pulling new plugin code into place### Runtime and dependency implicationsdiff --git a/docs/developer/plugins.md b/docs/developer/plugins.mdindex b16cb5428..88ca39fcb 100644--- a/docs/developer/plugins.md+++ b/docs/developer/plugins.md@@ -137,14 +137,16 @@ framework patches, or unmanaged files outside plugin-owned locations.Plugins can also include an optional `hooks.py` at the plugin root. Agent Zero loads this module on demand and calls exported functions by name through `helpers.plugins.call_plugin_hook(...)`.- `hooks.py` executes inside the **Agent Zero framework runtime and Python environment**.-- Use it for framework-internal operations such as install hooks, registration, cache preparation, file setup, or other work that needs direct access to framework internals.+- Use it for framework-internal operations such as install hooks, pre-update hooks, registration, cache preparation, file setup, or other work that needs direct access to framework internals.- Hook functions may be synchronous or async.- Hook modules are cached, so edits may require a plugin refresh or cache clear before changes are picked up.- Hooks should be reversible and cleanup-safe. Prefer plugin-owned paths and framework-managed state over permanent system modifications.Use `execute.py` when the user should explicitly decide when the operation runs. Use `hooks.py` or lifecycle extensions when the work belongs to framework-managed behavior.-Current built-in usage: the plugin installer calls `install()` from `hooks.py` after copying a plugin into place.+Current built-in usage:+- the plugin installer calls `install()` from `hooks.py` after copying a plugin into place+- the plugin updater calls `pre_update()` from `hooks.py` immediately before pulling new plugin code into place### Dependency and environment behaviordiff --git a/helpers/api.py b/helpers/api.pyindex 29ad11d1b..af767d18c 100644--- a/helpers/api.py+++ b/helpers/api.py@@ -217,7 +217,7 @@ def csrf_protect(f):def register_api_route(app: Flask, lock: ThreadLockType) -> None:- from helpers.extract_tools import load_classes_from_file+ from helpers.modules import load_classes_from_filefrom helpers import pluginsasync def _dispatch(path: str) -> BaseResponse:diff --git a/helpers/extension.py b/helpers/extension.pyindex 4948a5576..f257cb1f6 100644--- a/helpers/extension.py+++ b/helpers/extension.py@@ -1,6 +1,6 @@from abc import abstractmethodfrom typing import Any, Awaitable, Type, cast-from helpers import extract_tools, files+from helpers import modules, filesfrom helpers import cache, subagentsfrom typing import TYPE_CHECKINGfrom functools import wraps@@ -316,7 +316,7 @@ def _get_extensions(folder: str):if not files.exists(folder):return []- classes = extract_tools.load_classes_from_folder(folder, "*", Extension)+ classes = modules.load_classes_from_folder(folder, "*", Extension)cache.add(_EXTENSIONS_CACHE_AREA, folder, classes)return classesdiff --git a/helpers/extract_tools.py b/helpers/extract_tools.pyindex 5dc7f1c29..9b77e62c8 100644--- a/helpers/extract_tools.py+++ b/helpers/extract_tools.py@@ -1,14 +1,10 @@-import re, os, importlib, importlib.util, inspect-from types import ModuleType-from typing import Any, Type, TypeVar-from .dirty_json import DirtyJson-from .files import get_abs_path, deabsolute_path-import regex-from fnmatch import fnmatch-import inspect+from .dirty_json import DirtyJson+import regex, re+from helpers.modules import load_classes_from_file, load_classes_from_folder # keep here for backwards compatibility+from typing import Any-def json_parse_dirty(json:str) -> dict[str,Any] | None:+def json_parse_dirty(json: str) -> dict[str, Any] | None:if not json or not isinstance(json, str):return None@@ -16,25 +12,28 @@ def json_parse_dirty(json:str) -> dict[str,Any] | None:if ext_json:try:data = DirtyJson.parse_string(ext_json)- if isinstance(data,dict): return data+ if isinstance(data, dict):+ return dataexcept Exception:# If parsing fails, return None instead of crashingreturn Nonereturn None+def extract_json_object_string(content):- start = content.find('{')+ start = content.find("{")if start == -1:return ""# Find the first '{'- end = content.rfind('}')+ end = content.rfind("}")if end == -1:# If there's no closing '}', return from start to the endreturn content[start:]else:# If there's a closing '}', return the substring from start to end- return content[start:end+1]+ return content[start : end + 1]+def extract_json_string(content):# Regular expression pattern to match a JSON object@@ -49,106 +48,16 @@ def extract_json_string(content):else:return ""+def fix_json_string(json_string):# Function to replace unescaped line breaks within JSON string valuesdef replace_unescaped_newlines(match):- return match.group(0).replace('\n', '\\n')+ return match.group(0).replace("\n", "\\n")# Use regex to find string values and apply the replacement function- fixed_string = re.sub(r'(?<=: ")(.*?)(?=")', replace_unescaped_newlines, json_string, flags=re.DOTALL)- return fixed_string---T = TypeVar('T') # Define a generic type variable--def import_module(file_path: str) -> ModuleType:- # Handle file paths with periods in the name using importlib.util- abs_path = get_abs_path(file_path)- module_name = os.path.basename(abs_path).replace('.py', '')-- # Create the module spec and load the module- spec = importlib.util.spec_from_file_location(module_name, abs_path)- if spec is None or spec.loader is None:- raise ImportError(f"Could not load module from {abs_path}")-- module = importlib.util.module_from_spec(spec)- spec.loader.exec_module(module)- return module--def load_classes_from_folder(folder: str, name_pattern: str, base_class: Type[T], one_per_file: bool = True) -> list[Type[T]]:- classes = []- abs_folder = get_abs_path(folder)-- # Get all .py files in the folder that match the pattern, sorted alphabetically- py_files = sorted(- [file_name for file_name in os.listdir(abs_folder) if fnmatch(file_name, name_pattern) and file_name.endswith(".py")]+ fixed_string = re.sub(+ r'(?<=: ")(.*?)(?=")', replace_unescaped_newlines, json_string, flags=re.DOTALL)+ return fixed_string- # Iterate through the sorted list of files- for file_name in py_files:- file_path = os.path.join(abs_folder, file_name)- # Use the new import_module function- module = import_module(file_path)-- # Get all classes in the module- class_list = inspect.getmembers(module, inspect.isclass)-- # Filter for classes that are subclasses of the given base_class- # iterate backwards to skip imported superclasses- for cls in reversed(class_list):- if cls[1] is not base_class and issubclass(cls[1], base_class):- classes.append(cls[1])- if one_per_file:- break-- return classes--def load_classes_from_file(file: str, base_class: type[T], one_per_file: bool = True) -> list[type[T]]:- classes = []- # Use the new import_module function- module = import_module(file)-- # Get all classes in the module- class_list = inspect.getmembers(module, inspect.isclass)-- # Filter for classes that are subclasses of the given base_class- # iterate backwards to skip imported superclasses- for cls in reversed(class_list):- if cls[1] is not base_class and issubclass(cls[1], base_class):- classes.append(cls[1])- if one_per_file:- break-- return classes--def safe_call(func, *args, **kwargs):- sig = inspect.signature(func)-- bound_args = []- bound_kwargs = {}-- params = sig.parameters-- # Check if function accepts *args / **kwargs- accepts_var_args = any(p.kind == p.VAR_POSITIONAL for p in params.values())- accepts_var_kwargs = any(p.kind == p.VAR_KEYWORD for p in params.values())-- # Handle positional args- if accepts_var_args:- bound_args = args- else:- max_positional = sum(- 1 for p in params.values()- if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)- )- bound_args = args[:max_positional]-- # Handle kwargs- if accepts_var_kwargs:- bound_kwargs = kwargs- else:- bound_kwargs = {- k: v for k, v in kwargs.items() if k in params- }- return func(*bound_args, **bound_kwargs)\ No newline at end of filediff --git a/helpers/files.py b/helpers/files.pyindex fa1b15591..c77ab54cf 100644--- a/helpers/files.py+++ b/helpers/files.py@@ -47,9 +47,9 @@ def load_plugin_variables(if plugin_file and exists(plugin_file):- from helpers import extract_tools+ from helpers import modules- classes = extract_tools.load_classes_from_file(+ classes = modules.load_classes_from_file(plugin_file, VariablesPlugin, one_per_file=False)for cls in classes:diff --git a/helpers/functions.py b/helpers/functions.pynew file mode 100644index 000000000..9e85e6ab2--- /dev/null+++ b/helpers/functions.py@@ -0,0 +1,32 @@+import inspect++def safe_call(func, *args, **kwargs):+ sig = inspect.signature(func)++ bound_args = []+ bound_kwargs = {}++ params = sig.parameters++ # Check if function accepts *args / **kwargs+ accepts_var_args = any(p.kind == p.VAR_POSITIONAL for p in params.values())+ accepts_var_kwargs = any(p.kind == p.VAR_KEYWORD for p in params.values())++ # Handle positional args+ if accepts_var_args:+ bound_args = args+ else:+ max_positional = sum(+ 1+ for p in params.values()+ if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)+ )+ bound_args = args[:max_positional]++ # Handle kwargs+ if accepts_var_kwargs:+ bound_kwargs = kwargs+ else:+ bound_kwargs = {k: v for k, v in kwargs.items() if k in params}++ return func(*bound_args, **bound_kwargs)diff --git a/helpers/history.py b/helpers/history.pyindex 16b57f92a..43b0fbdde 100644--- a/helpers/history.py+++ b/helpers/history.py@@ -8,6 +8,8 @@ from typing import Coroutine, Literal, TypedDict, cast, Union, Dict, List, Anyfrom helpers import messages, tokens, settings, call_llmfrom enum import Enumfrom langchain_core.messages import BaseMessage, HumanMessage, SystemMessage, AIMessage+from plugins._model_config.helpers.model_config import get_chat_model_config+BULK_MERGE_COUNT = 3TOPICS_MERGE_COUNT = 3@@ -316,7 +318,7 @@ class History(Record):)def is_over_limit(self):- limit = _get_ctx_size_for_history()+ limit = self._get_ctx_size_for_history()total = self.get_tokens()return total > limit@@ -341,12 +343,70 @@ class History(Record):self.current = Topic(history=self)def output(self) -> list[OutputMessage]:+ self.trim_embeds(self._get_max_embeds())result: list[OutputMessage] = []result += [m for b in self.bulks for m in b.output()]result += [m for t in self.topics for m in t.output()]result += self.current.output()return result+ def trim_embeds(self, max_embeds: int) -> int:+ if max_embeds == -1:+ return 0++ embeds_count = 0+ removed = 0++ for record in reversed(self.bulks + self.topics + [self.current]):+ embeds_count, removed_now = self._trim_embeds_in_record(record, embeds_count, max_embeds)+ removed += removed_now++ return removed++ def remove_all_embeds(self) -> int:+ return self.trim_embeds(0)++ def _trim_embeds_in_record(+ self, record: Record, embeds_count: int, max_embeds: int+ ) -> tuple[int, int]:+ if isinstance(record, Message):+ if record.summary:+ return embeds_count, 0++ if not _is_raw_message(record.content):+ return embeds_count, 0++ raw_message = cast(dict[str, Any], record.content)+ raw_content = raw_message.get("raw_content", [])+ if not isinstance(raw_content, list):+ return embeds_count, 0++ embeds_in_message = sum(1 for item in raw_content if _is_embedded_data(item))+ if embeds_in_message <= 0:+ return embeds_count, 0++ if embeds_count + embeds_in_message > max_embeds:+ record.set_summary("embedded data removed")+ return embeds_count + embeds_in_message, embeds_in_message++ return embeds_count + embeds_in_message, 0++ if isinstance(record, Topic):+ removed = 0+ for message in reversed(record.messages):+ embeds_count, removed_now = self._trim_embeds_in_record(message, embeds_count, max_embeds)+ removed += removed_now+ return embeds_count, removed++ if isinstance(record, Bulk):+ removed = 0+ for nested in reversed(record.records):+ embeds_count, removed_now = self._trim_embeds_in_record(nested, embeds_count, max_embeds)+ removed += removed_now+ return embeds_count, removed++ return embeds_count, 0+@staticmethoddef from_dict(data: dict, history: "History"):history.counter = data.get("counter", 0)@@ -370,7 +430,7 @@ class History(Record):async def compress(self):compressed = False- total = _get_ctx_size_for_history()+ total = self._get_ctx_size_for_history()curr, hist, bulk = (self.get_current_topic_tokens(),self.get_topics_tokens(),@@ -472,6 +532,23 @@ class History(Record):await bulk.summarize()return bulk+ def _get_ctx_size_for_history(self) -> int:+ chat_cfg = get_chat_model_config(self.agent)+ ctx_length = int(chat_cfg.get("ctx_length", 128000))+ ctx_history = float(chat_cfg.get("ctx_history", 0.7))+ return int(ctx_length * ctx_history)++ def _get_max_embeds(self) -> int:+ chat_cfg = get_chat_model_config(self.agent)+ if not chat_cfg.get("vision", False):+ return 0++ max_embeds = int(chat_cfg.get("max_embeds", 10))+ if max_embeds <= 0:+ max_embeds = -1+ return max_embeds++def deserialize_history(json_data: str, agent) -> History:history = History(agent=agent)@@ -481,14 +558,6 @@ def deserialize_history(json_data: str, agent) -> History:return history-def _get_ctx_size_for_history() -> int:- from plugins._model_config.helpers.model_config import get_chat_model_config- chat_cfg = get_chat_model_config()- ctx_length = int(chat_cfg.get("ctx_length", 128000))- ctx_history = float(chat_cfg.get("ctx_history", 0.7))- return int(ctx_length * ctx_history)--def _stringify_output(output: OutputMessage, ai_label="ai", human_label="human"):return f'{ai_label if output["ai"] else human_label}: {_stringify_content(output["content"])}'@@ -500,8 +569,9 @@ def _stringify_content(content: MessageContent) -> str:# raw messages return preview or trimmed jsonif _is_raw_message(content):- preview: str = content.get("preview", "") # type: ignore- if preview:+ raw_message = cast(dict[str, Any], content)+ preview = raw_message.get("preview")+ if isinstance(preview, str) and preview:return previewtext = _json_dumps(content)if len(text) > RAW_MESSAGE_OUTPUT_TEXT_TRIM:@@ -516,7 +586,8 @@ def _output_content_langchain(content: MessageContent):if isinstance(content, str):return contentif _is_raw_message(content):- return content["raw_content"] # type: ignore+ raw_content = cast(dict[str, Any], content).get("raw_content")+ return raw_content if raw_content is not None else _json_dumps(content)try:return _json_dumps(content)except Exception as e:@@ -601,6 +672,10 @@ def _is_raw_message(obj: object) -> bool:return isinstance(obj, Mapping) and "raw_content" in obj+def _is_embedded_data(obj: object) -> bool:+ return isinstance(obj, Mapping) and obj.get("type") == "image_url"++def _json_dumps(obj):return json.dumps(obj, ensure_ascii=False)diff --git a/helpers/modules.py b/helpers/modules.pynew file mode 100644index 000000000..eb9b72332--- /dev/null+++ b/helpers/modules.py@@ -0,0 +1,97 @@++import re, os, importlib, importlib.util, inspect, sys+from types import ModuleType+from typing import Any, Type, TypeVar+from helpers.files import get_abs_path+from fnmatch import fnmatch+++T = TypeVar("T") # Define a generic type variable+++def import_module(file_path: str) -> ModuleType:+ # Handle file paths with periods in the name using importlib.util+ abs_path = get_abs_path(file_path)+ module_name = os.path.basename(abs_path).replace(".py", "")++ # Create the module spec and load the module+ spec = importlib.util.spec_from_file_location(module_name, abs_path)+ if spec is None or spec.loader is None:+ raise ImportError(f"Could not load module from {abs_path}")++ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def load_classes_from_folder(+ folder: str, name_pattern: str, base_class: Type[T], one_per_file: bool = True+) -> list[Type[T]]:+ classes = []+ abs_folder = get_abs_path(folder)++ # Get all .py files in the folder that match the pattern, sorted alphabetically+ py_files = sorted(+ [+ file_name+ for file_name in os.listdir(abs_folder)+ if fnmatch(file_name, name_pattern) and file_name.endswith(".py")+ ]+ )++ # Iterate through the sorted list of files+ for file_name in py_files:+ file_path = os.path.join(abs_folder, file_name)+ # Use the new import_module function+ module = import_module(file_path)++ # Get all classes in the module+ class_list = inspect.getmembers(module, inspect.isclass)++ # Filter for classes that are subclasses of the given base_class+ # iterate backwards to skip imported superclasses+ for cls in reversed(class_list):+ if cls[1] is not base_class and issubclass(cls[1], base_class):+ classes.append(cls[1])+ if one_per_file:+ break++ return classes+++def load_classes_from_file(+ file: str, base_class: type[T], one_per_file: bool = True+) -> list[type[T]]:+ classes = []+ # Use the new import_module function+ module = import_module(file)++ # Get all classes in the module+ class_list = inspect.getmembers(module, inspect.isclass)++ # Filter for classes that are subclasses of the given base_class+ # iterate backwards to skip imported superclasses+ for cls in reversed(class_list):+ if cls[1] is not base_class and issubclass(cls[1], base_class):+ classes.append(cls[1])+ if one_per_file:+ break++ return classes+++def purge_namespace(namespace: str):+ to_delete = [+ name+ for name in sys.modules+ if name == namespace or name.startswith(namespace + ".")+ ]++ # delete deepest first just to be tidy+ to_delete.sort(key=lambda n: n.count("."), reverse=True)++ for name in to_delete:+ del sys.modules[name]++ importlib.invalidate_caches()+ return to_delete\ No newline at end of filediff --git a/helpers/plugins.py b/helpers/plugins.pyindex eb503a54c..cfd64d133 100644--- a/helpers/plugins.py+++ b/helpers/plugins.py@@ -26,7 +26,8 @@ from helpers import (cache,extension,watchdog,- extract_tools,+ modules,+ functions,)from pydantic import BaseModel, Field@@ -129,7 +130,8 @@ def register_watchdogs():if plugin_name and plugin_name not in plugin_names:plugin_names.append(plugin_name)print_style.PrintStyle.debug("Plugins watchdog triggered", plugin_names)- after_plugin_change(plugin_names or None)+ python_change = any(path.endswith('.py') for path, _event in events)+ after_plugin_change(plugin_names or None, python_change=python_change)relevant_patterns = ["**/extensions/**/*", TOGGLE_FILE_PATTERN, HOOKS_SCRIPT]@@ -175,15 +177,31 @@ def register_watchdogs():@extension.extensible-def after_plugin_change(plugin_names: list[str] | None = None):- clear_plugin_cache()+def after_plugin_change(plugin_names: list[str] | None = None, python_change:bool=False):+ clear_plugin_cache(plugin_names)+ if python_change:+ refresh_plugin_modules(plugin_names)send_frontend_reload_notification(plugin_names)-def clear_plugin_cache():+def refresh_plugin_modules(plugin_names: list[str] | None = None):+ if plugin_names:+ clear_plugins = any(name.startswith("_") for name in plugin_names)+ clear_usr_plugins = any(not name.startswith("_") for name in plugin_names)+ if clear_plugins:+ modules.purge_namespace("plugins")+ if clear_usr_plugins:+ modules.purge_namespace("usr.plugins")+ else:+ modules.purge_namespace("plugins")+ modules.purge_namespace("usr.plugins")+++def clear_plugin_cache(plugin_names: list[str] | None = None):areas = ["*(plugins)*", "*(extensions)*", "*(api)*"]for area in areas:cache.clear(area)+from helpers.websocket_manager import send_dataDeferredTask().start_task(@@ -378,7 +396,7 @@ def delete_plugin(plugin_name: str):raise ValueError("Only custom plugins can be deleted")# delete additional plugin folders- assets = find_plugin_assets("", plugin_name=plugin_name)+ assets = [asset for asset in find_plugin_assets("", plugin_name=plugin_name) if not asset["path"].startswith(plugin_dir)]for asset in assets:files.delete_dir(asset["path"])@@ -386,10 +404,13 @@ def delete_plugin(plugin_name: str):[plugin_name]) # send before deletion to properly check the extensions, second notification will be skipped automatically+ # does it have python files?+ python_change = bool(files.find_existing_paths_by_pattern(plugin_dir+"/**/*.py"))+# delete main plugin folderfiles.delete_dir(plugin_dir)- after_plugin_change([plugin_name])+ after_plugin_change([plugin_name], python_change=python_change)def get_plugin_paths(*subpaths: str) -> List[str]:@@ -854,9 +875,7 @@ def call_plugin_hook(return default # plugin directory not found, skip hookshooks_script = files.get_abs_path(plugin_dir, HOOKS_SCRIPT)hooks = (- extract_tools.import_module(hooks_script)- if files.exists(hooks_script)- else None+ modules.import_module(hooks_script) if files.exists(hooks_script) else None)cache.add(HOOKS_CACHE_AREA, plugin_name, hooks)else:@@ -870,11 +889,9 @@ def call_plugin_hook(return defaultif asyncio.iscoroutinefunction(hook):- return asyncio.run(- extract_tools.safe_call(hook, *args, default=default, **kwargs)- )+ return asyncio.run(functions.safe_call(hook, *args, default=default, **kwargs))- return extract_tools.safe_call(hook, *args, default=default, **kwargs)+ return functions.safe_call(hook, *args, default=default, **kwargs)def _apply_defaults_from_env(plugin_name: str, config: dict[str, Any]):diff --git a/helpers/ws.py b/helpers/ws.pyindex 314f197a8..82c79d0a4 100644--- a/helpers/ws.py+++ b/helpers/ws.py@@ -119,7 +119,7 @@ def register_ws_namespace(webapp: Flask,lock: ThreadLockType,) -> None:- from helpers.extract_tools import load_classes_from_file+ from helpers.modules import load_classes_from_filefrom helpers import plugins, runtimedef _resolve_handler(path: str) -> type[WsHandler] | None:diff --git a/plugins/_error_retry/default_config.yaml b/plugins/_error_retry/default_config.yamlindex fe8b4f74f..915fe4581 100644--- a/plugins/_error_retry/default_config.yaml+++ b/plugins/_error_retry/default_config.yaml@@ -1 +1,2 @@-retries: 1\ No newline at end of file+retries: 1+try_clear_embeds: true\ No newline at end of filediff --git a/plugins/_error_retry/extensions/python/_functions/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.pyindex 222a9f74d..e061e4516 100644--- a/plugins/_error_retry/extensions/python/_functions/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@@ -1,10 +1,11 @@import asynciofrom datetime import datetime, timezone+import litellmfrom helpers.extension import Extensionfrom agent import LoopDatafrom helpers.localization import Localizationfrom helpers.errors import RepairableException, HandledException-from helpers import errors+from helpers import errors, pluginsfrom helpers.print_style import PrintStylefrom plugins._error_retry.extensions.python._functions.agent.Agent.monologue.start._10_reset_critical_exception_counter import DATA_NAME_COUNTER@@ -28,6 +29,7 @@ class RetryCriticalException(Extension):counter = self.agent.get_data(DATA_NAME_COUNTER) or 0if counter >= max_retries:+ self.when_critical(data)returnself.agent.set_data(DATA_NAME_COUNTER, counter + 1)@@ -51,4 +53,37 @@ class RetryCriticalException(Extension):data["exception"] = None++ def when_critical(self, data: dict = {}):+ if not self.agent:+ return++ self.try_clear_embeds(data)++ def try_clear_embeds(self, data: dict = {}):+ """Try to clear embeds before failing on LiteLLM errors"""+ if not self.agent:+ return++ exc = data.get("exception")+ if not isinstance(exc, litellm.exceptions.BadRequestError):+ return++ cfg = plugins.get_plugin_config("_error_retry", agent=self.agent) or {}+ if not cfg.get("try_clear_embeds", False):+ return++ removed = self.agent.history.remove_all_embeds()+ if removed <= 0:+ return++ data["exception"] = None+ self.agent.context.log.log(+ type="warning",+ heading="Cleared embedded media from history",+ content=f"Persistent LiteLLM bad request detected. Removed {removed} embedded media messages from history to help recover.",+ )+ PrintStyle(font_color="orange", padding=True).print(+ f"Cleared {removed} embedded media messages from history after persistent LiteLLM bad request."+ )\ No newline at end of filediff --git a/plugins/_error_retry/webui/config.html b/plugins/_error_retry/webui/config.htmlindex 20b95cfc0..662e4aff4 100644--- a/plugins/_error_retry/webui/config.html+++ b/plugins/_error_retry/webui/config.html@@ -24,6 +24,21 @@x-model.number="config.retries" /></div></div>++ <div class="field">+ <div class="field-label">+ <div class="field-title">Try clearing embedded media</div>+ <div class="field-description">+ If LiteLLM errors keep happening, the framework can remove embedded media from history and try again to help recover from stuck states.+ </div>+ </div>+ <div class="field-control">+ <label class="toggle">+ <input type="checkbox" x-model="config.try_clear_embeds" x-init="if (config.try_clear_embeds === undefined || config.try_clear_embeds === null) config.try_clear_embeds = true" />+ <span class="toggler"></span>+ </label>+ </div>+ </div></div></template></div>diff --git a/plugins/_model_config/default_config.yaml b/plugins/_model_config/default_config.yamlindex 15e3e1a56..b9b322705 100644--- a/plugins/_model_config/default_config.yaml+++ b/plugins/_model_config/default_config.yaml@@ -7,6 +7,7 @@ chat_model:ctx_length: 128000ctx_history: 0.7vision: true+ max_embeds: 10rl_requests: 0rl_input: 0rl_output: 0diff --git a/plugins/_model_config/webui/config.html b/plugins/_model_config/webui/config.htmlindex 39c0f948d..a62047731 100644--- a/plugins/_model_config/webui/config.html+++ b/plugins/_model_config/webui/config.html@@ -188,6 +188,19 @@</label></div></div>+ <template x-if="config.chat_model.vision">+ <div class="field">+ <div class="field-label">+ <div class="field-title">Max embeds</div>+ <div class="field-description">+ Maximum number of embedded images used by the chat model. Set to 0 for unlimited.+ </div>+ </div>+ <div class="field-control">+ <input type="number" min="0" x-model.number="config.chat_model.max_embeds" x-init="if (!config.chat_model.max_embeds) config.chat_model.max_embeds = 10" />+ </div>+ </div>+ </template></div></template>@@ -258,17 +271,6 @@</div></div>- <!-- Browser HTTP Headers -->- <template x-if="section.key === 'chat_model'">- <div class="field field-full">- <div class="field-label">- <div class="field-title">Browser HTTP Headers</div>- <div class="field-description">- Custom HTTP headers sent with browser requests. The browser agent uses the main model. Format is KEY=VALUE, one per line.- </div>- </div>- </div>- </template></div></template>diff --git a/plugins/_model_config/webui/main.html b/plugins/_model_config/webui/main.htmlindex 196f71233..4fafd1fa7 100644--- a/plugins/_model_config/webui/main.html+++ b/plugins/_model_config/webui/main.html@@ -183,12 +183,6 @@@change="preset.chat.kwargs = $store.modelConfig.textToKwargs(preset.chat._kwargs_text)"></textarea></div></div>- <div class="field field-full">- <div class="field-label">- <div class="field-title">Browser HTTP Headers</div>- <div class="field-description">Custom HTTP headers sent with browser requests. The browser agent uses the main model. Format is KEY=VALUE, one per line.</div>- </div>- </div><div class="preset-subheader">Utility Model <span style="opacity:0.5; font-size:0.75rem;">(optional — falls back to the configured Utility Model)</span></div><div class="field">diff --git a/plugins/_plugin_installer/helpers/install.py b/plugins/_plugin_installer/helpers/install.pyindex d4e14ff0a..75ffb203d 100644--- a/plugins/_plugin_installer/helpers/install.py+++ b/plugins/_plugin_installer/helpers/install.py@@ -134,7 +134,11 @@ def install_from_zip(zip_path: str, original_filename: str | None = None) -> dicfiles.delete_dir(dest)raise- after_plugin_change([plugin_name])++ # does it have python files?+ python_change = bool(files.find_existing_paths_by_pattern(dest+"/**/*.py"))++ after_plugin_change([plugin_name], python_change=python_change)return {"success": True,@@ -209,7 +213,10 @@ def install_from_git(url: str, token: str | None = None, plugin_name: str = "",files.delete_dir(final_dir)raise- after_plugin_change([plugin_name])+ # does it have python files?+ python_change = bool(files.find_existing_paths_by_pattern(final_dir+"/**/*.py"))++ after_plugin_change([plugin_name],python_change=python_change)return {"success": True,@@ -232,6 +239,14 @@ def update_from_git(plugin_name: str) -> dict:if not files.is_in_dir(plugin_dir, custom_plugins_dir):raise ValueError("Only custom plugins can be updated")+ try:+ run_pre_update_hook(plugin_name)+ except Exception as e:+ print_style.PrintStyle.error(+ f"Failed to run pre-update hook for {plugin_name}: {e}"+ )+ raise+try:repo = git.update_repo(plugin_dir)meta = plugins.get_plugin_meta(plugin_name)@@ -268,6 +283,8 @@ def update_from_git(plugin_name: str) -> dict:def run_install_hook(plugin_name: str):return plugins.call_plugin_hook(plugin_name, "install")+def run_pre_update_hook(plugin_name: str):+ return plugins.call_plugin_hook(plugin_name, "pre_update")def get_plugin_hub_index() -> dict[str, Any]:"""Return the plugin index plus installed Plugin Hub keys."""diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 97c91542b..c7f26bf2f 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -275,9 +275,11 @@ Users trigger it from the Plugins UI. Treat it as a manual, rerunnable operationIf your plugin needs framework-internal hook points, add a `hooks.py` file at the plugin root. The framework can call exported functions by name via `helpers.plugins.call_plugin_hook(...)`.- `hooks.py` runs inside the **Agent Zero framework runtime**, not the separate agent execution environment.-- Use it for things like install hooks, plugin registration work, cache setup, file preparation, or other internal framework operations.+- Use it for things like install hooks, pre-update hooks, plugin registration work, cache setup, file preparation, or other internal framework operations.+- Current built-in usage:+ - the plugin installer calls `install()` in `hooks.py` after placing a plugin in `usr/plugins/`+ - the plugin updater calls `pre_update()` in `hooks.py` immediately before pulling new plugin code into place- Hook functions may be sync or async.-- Current example: the plugin installer calls `install()` in `hooks.py` after placing a plugin in `usr/plugins/`.- Hooks should be reversible and cleanup-safe. Prefer framework-managed state and plugin-owned paths over permanent system modifications.### Environment targeting rulesdiff --git a/skills/a0-debug-plugin/SKILL.md b/skills/a0-debug-plugin/SKILL.mdindex 46dc44f48..0ffa2d675 100644--- a/skills/a0-debug-plugin/SKILL.md+++ b/skills/a0-debug-plugin/SKILL.md@@ -119,6 +119,20 @@ print('Done')"```+If the `pre_update()` hook is not running before plugin updates:+- Check the function is named exactly `pre_update`+- Check for exceptions in the function+- Manually trigger it in the **framework runtime** the same way:++```bash+cd /a0 && /opt/venv-a0/bin/python -c "+import asyncio+from helpers.plugins import call_plugin_hook+asyncio.run(call_plugin_hook('<plugin_name>', 'pre_update'))+print('Done')+"+```+---## 8. Check Agent Zero logsdiff --git a/skills/a0-manage-plugin/SKILL.md b/skills/a0-manage-plugin/SKILL.mdindex b4f89b8be..13432b11b 100644--- a/skills/a0-manage-plugin/SKILL.md+++ b/skills/a0-manage-plugin/SKILL.md@@ -234,7 +234,7 @@ Or simply restart Agent Zero - on startup it re-scans `usr/plugins/` fresh.## Update a Plugin-> A dedicated update endpoint is being added to the framework. Until it lands, use the flow below.+> The framework update flow now calls `pre_update()` from `hooks.py` immediately before pulling new plugin code into place, then re-runs `install()` after the update if that hook exists.### Checking for updatesdiff --git a/skills/a0-plugin-router/SKILL.md b/skills/a0-plugin-router/SKILL.mdindex 8e559ddf9..305b87980 100644--- a/skills/a0-plugin-router/SKILL.md+++ b/skills/a0-plugin-router/SKILL.md@@ -76,7 +76,7 @@ always_enabled: false # forces ON, disables toggle (framework use only)| `extensions/webui/<point>/` | HTML/JS injected into UI breakpoints || `webui/config.html` | Plugin settings UI || `webui/*.html`, `webui/*.js` | Full plugin pages and Alpine stores |-| `hooks.py` | Framework runtime hooks (install, cache, registration) |+| `hooks.py` | Framework runtime hooks (install, pre_update, cache, registration) || `execute.py` | User-triggered script (setup, maintenance, repair) || `default_config.yaml` | Settings defaults || `README.md` | Optional locally; strongly recommended for community plugins so Plugin Hub users can inspect the plugin |diff --git a/skills/a0-review-plugin/SKILL.md b/skills/a0-review-plugin/SKILL.mdindex 92f0d8933..94373cb7e 100644--- a/skills/a0-review-plugin/SKILL.md+++ b/skills/a0-review-plugin/SKILL.md@@ -52,7 +52,7 @@ Inspect the plugin directory layout:- [ ] If `agents/` exists: agent profiles with `<profile>/agent.yaml` (standard directory)- [ ] If `conf/` exists: configuration files such as `model_providers.yaml` (standard directory)- [ ] If `webui/config.html` exists: plugin must declare at least one `settings_sections` entry-- [ ] If `hooks.py` exists: warn if it does NOT contain an `install` function (common oversight)+- [ ] If `hooks.py` exists: review whether it defines the lifecycle hook functions the plugin appears to rely on, especially `install` and `pre_update` when the plugin needs install-time or update-time behavior- [ ] If `execute.py` exists: check it has a `main()` function and `if __name__ == "__main__": sys.exit(main())`- [ ] `LICENSE` at plugin root: Agent Zero does not require it for local plugins, but it is **required** at the repo root before submitting to the Plugin Index. If missing → **WARN** — `LICENSE absent — required for community contribution (Plugin Index); optional for local-only use`- [ ] `default_config.yaml` (if present): valid YAMLdiff --git a/skills/a0-review-plugin/checklists.md b/skills/a0-review-plugin/checklists.mdindex 76cea262d..40833b8d6 100644--- a/skills/a0-review-plugin/checklists.md+++ b/skills/a0-review-plugin/checklists.md@@ -206,7 +206,7 @@ save_plugin_config(## hooks.py Environment Targeting```python-# hooks.py - install hook example+# hooks.py - install/pre_update hook exampleimport subprocessimport sys@@ -215,6 +215,11 @@ def install():# This installs into the Agent Zero FRAMEWORK runtime (/opt/venv-a0)subprocess.run([sys.executable, "-m", "pip", "install", "some-package==1.0.0"], check=True)+def pre_update():+ """Called by framework immediately before plugin update pulls new code into place."""+ # This installs into the Agent Zero FRAMEWORK runtime (/opt/venv-a0)+ subprocess.run([sys.executable, "-m", "pip", "install", "some-package==1.0.0"], check=True)+async def async_hook():"""Async hooks are also supported."""passdiff --git a/tools/vision_load.py b/tools/vision_load.pyindex 840f70162..ae654419a 100644--- a/tools/vision_load.py+++ b/tools/vision_load.py@@ -1,7 +1,7 @@import base64from helpers.print_style import PrintStylefrom helpers.tool import Tool, Response-from helpers import runtime, files, images+from helpers import runtime, files, images, pluginsfrom mimetypes import guess_typefrom helpers import history@@ -15,9 +15,15 @@ class VisionLoad(Tool):async def execute(self, paths: list[str] = [], **kwargs) -> Response:self.images_dict = {}+ self.loaded_paths: list[str] = []+ self.skipped_paths: list[str] = []template: list[dict[str, str]] = [] # type: ignore- for path in paths:+ max_embeds = self._get_max_embeds()+ limited_paths = paths if max_embeds <= 0 else paths[-max_embeds:]+ self.skipped_paths = paths[:-max_embeds] if max_embeds > 0 and len(paths) > max_embeds else []++ for path in limited_paths:if not await runtime.call_development_function(files.exists, str(path)):continue@@ -44,6 +50,7 @@ class VisionLoad(Tool):# Construct the data URL (always JPEG after compression)self.images_dict[path] = file_content_b64+ self.loaded_paths.append(path)except Exception as e:self.images_dict[path] = NonePrintStyle().error(f"Error processing image {path}: {e}")@@ -51,12 +58,24 @@ class VisionLoad(Tool):return Response(message="dummy", break_loop=False)+ def _get_max_embeds(self) -> int:+ cfg = plugins.get_plugin_config("_model_config", agent=self.agent) or {}+ chat_cfg = cfg.get("chat_model", {})+ max_embeds = chat_cfg.get("max_embeds", 10)+ return int(max_embeds or 0)+async def after_execution(self, response: Response, **kwargs):# build image data messages for LLMs, or error messagecontent = []+ loaded_summary = "\n".join(self.loaded_paths) if self.loaded_paths else "none"+ skipped_summary = "\n".join(self.skipped_paths) if self.skipped_paths else "none"+ summary = (+ f"Loaded images:\n{loaded_summary}\n\n"+ f"Skipped images (max {self._get_max_embeds()} loaded at a time according to model configuration):\n{skipped_summary}"+ )if self.images_dict:- self.agent.hist_add_tool_result(self.name, f"Processed {len(self.images_dict)} images") # some model providers break when they get have images in message history without text+ self.agent.hist_add_tool_result(self.name, summary)for path, image in self.images_dict.items():if image:content.append(@@ -78,13 +97,13 @@ class VisionLoad(Tool):False, content=msg, tokens=TOKENS_ESTIMATE * len(content))else:- self.agent.hist_add_tool_result(self.name, "No images processed")+ self.agent.hist_add_tool_result(self.name, summary if self.skipped_paths else "No images processed")# print and log short versionmessage = ("No images processed"- if not self.images_dict- else f"{len(self.images_dict)} images processed"+ if not self.images_dict and not self.skipped_paths+ else f"{len(self.loaded_paths)} images loaded, {len(self.skipped_paths)} skipped")PrintStyle(font_color="#1B4F72", background_color="white", padding=True, bold=True