Skip to content

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.md
index 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 implications
diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md
index 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 behavior
diff --git a/helpers/api.py b/helpers/api.py
index 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_file
from helpers import plugins
async def _dispatch(path: str) -> BaseResponse:
diff --git a/helpers/extension.py b/helpers/extension.py
index 4948a5576..f257cb1f6 100644
--- a/helpers/extension.py
+++ b/helpers/extension.py
@@ -1,6 +1,6 @@
from abc import abstractmethod
from typing import Any, Awaitable, Type, cast
-from helpers import extract_tools, files
+from helpers import modules, files
from helpers import cache, subagents
from typing import TYPE_CHECKING
from 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 classes
diff --git a/helpers/extract_tools.py b/helpers/extract_tools.py
index 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 data
except Exception:
# If parsing fails, return None instead of crashing
return None
return 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 end
return 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 values
def 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 file
diff --git a/helpers/files.py b/helpers/files.py
index 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.py
new file mode 100644
index 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.py
index 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, Any
from helpers import messages, tokens, settings, call_llm
from enum import Enum
from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage, AIMessage
+from plugins._model_config.helpers.model_config import get_chat_model_config
+
BULK_MERGE_COUNT = 3
TOPICS_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
+
@staticmethod
def 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 json
if _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 preview
text = _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 content
if _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.py
new file mode 100644
index 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 file
diff --git a/helpers/plugins.py b/helpers/plugins.py
index 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_data
DeferredTask().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 folder
files.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 hooks
hooks_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 default
if 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.py
index 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_file
from helpers import plugins, runtime
def _resolve_handler(path: str) -> type[WsHandler] | None:
diff --git a/plugins/_error_retry/default_config.yaml b/plugins/_error_retry/default_config.yaml
index 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 file
diff --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.py
index 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 asyncio
from datetime import datetime, timezone
+import litellm
from helpers.extension import Extension
from agent import LoopData
from helpers.localization import Localization
from helpers.errors import RepairableException, HandledException
-from helpers import errors
+from helpers import errors, plugins
from helpers.print_style import PrintStyle
from 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 0
if counter >= max_retries:
+ self.when_critical(data)
return
self.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 file
diff --git a/plugins/_error_retry/webui/config.html b/plugins/_error_retry/webui/config.html
index 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.yaml
index 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: 128000
ctx_history: 0.7
vision: true
+ max_embeds: 10
rl_requests: 0
rl_input: 0
rl_output: 0
diff --git a/plugins/_model_config/webui/config.html b/plugins/_model_config/webui/config.html
index 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.html
index 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 &#x2014; 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.py
index 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) -> dic
files.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.md
index 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 operation
If 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 rules
diff --git a/skills/a0-debug-plugin/SKILL.md b/skills/a0-debug-plugin/SKILL.md
index 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 logs
diff --git a/skills/a0-manage-plugin/SKILL.md b/skills/a0-manage-plugin/SKILL.md
index 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 updates
diff --git a/skills/a0-plugin-router/SKILL.md b/skills/a0-plugin-router/SKILL.md
index 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.md
index 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 YAML
diff --git a/skills/a0-review-plugin/checklists.md b/skills/a0-review-plugin/checklists.md
index 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 example
import subprocess
import 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."""
pass
diff --git a/tools/vision_load.py b/tools/vision_load.py
index 840f70162..ae654419a 100644
--- a/tools/vision_load.py
+++ b/tools/vision_load.py
@@ -1,7 +1,7 @@
import base64
from helpers.print_style import PrintStyle
from helpers.tool import Tool, Response
-from helpers import runtime, files, images
+from helpers import runtime, files, images, plugins
from mimetypes import guess_type
from 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] = None
PrintStyle().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 message
content = []
+ 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 version
message = (
"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