Skip to content

Agent Zero AI framework

Upgrade LiteLLM and OpenAI with framework startup migration

Alessandrob91384f4fb87
diff --git a/AGENTS.md b/AGENTS.md
index ed88cc9c7..f0987dae5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,7 @@
- `models.py` owns model-provider configuration and LiteLLM integration. `get_api_key_raw()` reads the stored key or key list for settings/editing; `get_api_key()` selects a runtime key and runs provider extension hooks.
- `models.apply_rate_limiter` skips token counting and returns no limiter when all request, input, and output limits are unset; any configured limit retains normal accounting.
- `requirements.txt` includes HTTPX's SOCKS extra so framework clients support SOCKS proxy environment variables before plugin setup.
+- LiteLLM and OpenAI pins must remain compatible. Retain shared dependency security floors and verify upgrades with installed-SDK HTTP tests in `tests/test_litellm_sdk.py` using the framework runtime.
- Native agent-turn response callbacks may receive a display-only commentary preview as their full text; legacy callbacks, accumulated model output, usage and native dispatch retain the original text and result metadata.
- `run_ui.py` is the WebUI entry point.
- `DockerfileLocal` must remain compatible with the contracts under `docker/`.
@@ -45,6 +46,7 @@
- Copy live core-plugin changes back into tracked source under `plugins/`.
- Develop new custom plugins under ignored `usr/plugins/`; tracked bundled plugins live under `plugins/`.
- Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.
+- Dependency changes must cover both image installation declarations and existing self-updated instances. Use startup migrations for core dependencies and the owning installation hooks for plugin dependencies.
## Permissions
diff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.md
index 4f87e56e7..719577cbe 100644
--- a/extensions/python/startup_migration/AGENTS.md
+++ b/extensions/python/startup_migration/AGENTS.md
@@ -13,6 +13,8 @@
- Migrations must be safe to run repeatedly.
- Preserve user data and create backups or reversible paths when changing durable state.
- Keep long-running work bounded and observable.
+- `_05_framework_dependencies.py` applies the LiteLLM/OpenAI pins and shared security floors from root `requirements.txt` on Docker startup. Already-current and non-Docker environments skip installation; failures stop startup. Extend its package scope when future core dependency changes need self-update installation.
+- After changing framework packages, reuse `helpers.process.restart_process()` before serving requests so imported SDK modules are refreshed. Keep installation within 60 seconds to leave startup time within older self-updaters' health-check window; Git rollback does not restore Python packages.
- `_10_self_update_manager.py` may replace `/exe/self_update_manager.py` from the repository copy when the installed runtime updater is stale; it must validate required safety markers and keep a backup before replacement.
- Required updater capabilities include immutable rollback-stash identity (`get_top_stash_oid`), so runtimes using moving stash selectors are upgraded on startup.
- After synchronizing a stale self-update manager, `_10_self_update_manager.py` starts that manager's best-effort Codex CLI refresh in the background so the update that introduces the hook does not need a second restart.
diff --git a/extensions/python/startup_migration/_05_framework_dependencies.py b/extensions/python/startup_migration/_05_framework_dependencies.py
new file mode 100644
index 000000000..04f729b38
--- /dev/null
+++ b/extensions/python/startup_migration/_05_framework_dependencies.py
@@ -0,0 +1,67 @@
+import importlib.metadata
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+from packaging.requirements import Requirement
+
+from helpers import files, process, runtime
+from helpers.extension import Extension
+from helpers.print_style import PrintStyle
+
+
+_REQUIREMENTS_FILE = Path(files.get_abs_path("requirements.txt"))
+_PACKAGES = {
+ "litellm", "openai", "python-dotenv", "aiohttp", "anyio", "urllib3",
+ "filelock", "fsspec", "multidict",
+}
+
+
+class FrameworkDependencies(Extension):
+ def execute(self, **kwargs):
+ if not runtime.is_dockerized():
+ return
+ requirements = _requirements()
+ outdated = _outdated(requirements)
+ if not outdated:
+ return
+ uv = shutil.which("uv")
+ if not uv:
+ raise RuntimeError("Framework dependency update requires 'uv'.")
+ PrintStyle.info("Updating framework dependencies:", ", ".join(outdated))
+ subprocess.check_call(
+ [uv, "pip", "install", "--python", sys.executable, *map(str, requirements)],
+ timeout=60,
+ )
+ outdated = _outdated(requirements)
+ if outdated:
+ raise RuntimeError(f"Framework dependencies still unavailable after installation: {outdated}")
+ # Models were imported before startup migrations; load the upgraded SDKs.
+ process.restart_process()
+
+
+def _requirements() -> list[Requirement]:
+ requirements = []
+ for line in _REQUIREMENTS_FILE.read_text(encoding="utf-8").splitlines():
+ line = line.partition("#")[0].strip()
+ if line:
+ requirement = Requirement(line)
+ if requirement.name in _PACKAGES:
+ requirements.append(requirement)
+ missing = _PACKAGES - {requirement.name for requirement in requirements}
+ if missing:
+ raise RuntimeError(f"Framework requirements missing from {_REQUIREMENTS_FILE}: {sorted(missing)}")
+ return requirements
+
+
+def _outdated(requirements: list[Requirement]) -> list[str]:
+ outdated = []
+ for requirement in requirements:
+ try:
+ installed = importlib.metadata.version(requirement.name)
+ except importlib.metadata.PackageNotFoundError:
+ installed = None
+ if installed is None or installed not in requirement.specifier:
+ outdated.append(str(requirement))
+ return outdated
diff --git a/requirements.txt b/requirements.txt
index bd1cbeeee..ef4b7ebbf 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -20,8 +20,8 @@ langchain-core==0.3.49
langchain-community==0.3.19
langchain-unstructured==0.1.6
liteparse==2.0.3
-litellm==1.88.1 # CVE-2026-42271 fix: patched floor is 1.83.7
-openai==2.41.1
+litellm==1.104.0
+openai==2.54.0
openai-whisper==20250625
lxml_html_clean>=0.4.0 # CVE-2024-52595 fix: XSS CWE-79 CVSS 8.4
markdown==3.7
@@ -30,7 +30,7 @@ newspaper3k==0.2.8
paramiko==3.5.0
patchright==1.61.2
pypdf==6.0.0
-python-dotenv==1.1.0
+python-dotenv==1.2.2
pytz==2024.2
sentence-transformers==3.0.1
tiktoken==0.8.0
@@ -64,7 +64,12 @@ wsproto>=1.2.0
Pillow>=10.2.0 # security floor: heap buffer overflow CWE-122, eval injection CWE-95, DoS CWE-400
nltk>=3.9.3 # security floor: RCE CWE-94, code injection CWE-94
h11>=0.16.0 # security floor: HTTP request smuggling CWE-444
-urllib3>=2.6.0 # security floor: resource exhaustion CWE-770, data amplification CWE-409
+urllib3>=2.8.0 # security floor: proxy TLS verification and streaming resource exhaustion
cryptography>=46.0.0 # security floor: insufficient data authenticity CWE-345
werkzeug>=3.0.3 # security floor: RCE CWE-94
starlette==1.0.1 # security fix: Host header validation bypass GHSA-86qp-5c8j-p5mr
+aiohttp>=3.14.3 # security floor: malformed-response parser and WebSocket handling
+anyio>=4.14.2 # security floor: TLS hostname validation and subprocess handling
+filelock>=3.20.3 # security floor: symlink attacks during lock creation
+fsspec>=2026.6.0 # security floor: template injection in reference filesystems
+multidict>=6.9.1 # security floor: items-view reference leaks
diff --git a/tests/AGENTS.md b/tests/AGENTS.md
index 6e97fb72d..fb21eede7 100644
--- a/tests/AGENTS.md
+++ b/tests/AGENTS.md
@@ -32,6 +32,8 @@
- Run `pytest` for broad changes.
- Run `pytest tests/test_name.py` for narrow changes and mention any broader test gaps at closeout.
+- Run `pytest tests/test_litellm_sdk.py -q` for LiteLLM/OpenAI upgrades. Its loopback provider exercises the installed SDK's sync/async calls, streaming, tool/state preservation, fallback, embeddings, and Anthropic cache markers without real keys or external requests.
+- Run `pytest tests/test_framework_dependencies.py -q` for dependency migration changes; verify stale self-update environments, process restart, and already-current image installs.
## Child DOX Index
diff --git a/tests/test_framework_dependencies.py b/tests/test_framework_dependencies.py
new file mode 100644
index 000000000..49a448aee
--- /dev/null
+++ b/tests/test_framework_dependencies.py
@@ -0,0 +1,90 @@
+import importlib.metadata
+import subprocess
+import sys
+
+import pytest
+
+from extensions.python.startup_migration import _05_framework_dependencies as migration
+
+
+def installed(monkeypatch):
+ requirements = migration._requirements()
+ versions = {req.name: next(iter(req.specifier)).version for req in requirements}
+
+ def version(name):
+ if name not in versions:
+ raise importlib.metadata.PackageNotFoundError(name)
+ return versions[name]
+
+ monkeypatch.setattr(migration.runtime, "is_dockerized", lambda: True)
+ monkeypatch.setattr(migration.process, "restart_process", lambda: pytest.fail("Unexpected restart"))
+ monkeypatch.setattr(migration.importlib.metadata, "version", version)
+ monkeypatch.setattr(migration.shutil, "which", lambda _name: "/usr/bin/uv")
+ return versions
+
+
[email protected]("package,old_version", [
+ ("litellm", "1.88.1"), ("openai", "2.41.1"),
+ ("aiohttp", "3.14.0"), ("filelock", None),
+])
+def test_self_update_installs_requirements_and_restarts_once(monkeypatch, installed, package, old_version):
+ target = installed.copy()
+ installed.pop(package)
+ if old_version:
+ installed[package] = old_version
+ calls = []
+ restarts = []
+
+ def install(command, **kwargs):
+ calls.append((command, kwargs))
+ installed.update(target)
+
+ monkeypatch.setattr(migration.subprocess, "check_call", install)
+ monkeypatch.setattr(migration.process, "restart_process", lambda: restarts.append(True))
+ extension = migration.FrameworkDependencies(None)
+ extension.execute()
+ extension.execute()
+ assert restarts == [True]
+ assert len(calls) == 1
+ command, kwargs = calls[0]
+ assert command[:5] == ["/usr/bin/uv", "pip", "install", "--python", sys.executable]
+ assert set(command[5:]) == {
+ "litellm==1.104.0", "openai==2.54.0", "python-dotenv==1.2.2",
+ "aiohttp>=3.14.3", "anyio>=4.14.2", "urllib3>=2.8.0",
+ "filelock>=3.20.3", "fsspec>=2026.6.0", "multidict>=6.9.1",
+ }
+ assert kwargs == {"timeout": 60}
+
+
+def test_current_image_skips_installer_and_restart(monkeypatch, installed):
+ installed["filelock"] = "3.32.7"
+ monkeypatch.setattr(migration.shutil, "which", lambda _name: pytest.fail("Installer lookup"))
+ migration.FrameworkDependencies(None).execute()
+
+
+ subprocess.CalledProcessError(1, "uv"), subprocess.TimeoutExpired("uv", 60),
+])
+def test_failed_install_stops_startup_without_restart(monkeypatch, installed, error):
+ installed.pop("litellm")
+
+ def fail(*args, **kwargs):
+ raise error
+
+ monkeypatch.setattr(migration.subprocess, "check_call", fail)
+ with pytest.raises(type(error)):
+ migration.FrameworkDependencies(None).execute()
+
+
+def test_install_must_satisfy_requirements_before_restart(monkeypatch, installed):
+ installed["openai"] = "2.41.1"
+ monkeypatch.setattr(migration.subprocess, "check_call", lambda *args, **kwargs: None)
+ with pytest.raises(RuntimeError, match="still unavailable"):
+ migration.FrameworkDependencies(None).execute()
+
+
+def test_non_docker_environment_skips_dependency_migration(monkeypatch):
+ monkeypatch.setattr(migration.runtime, "is_dockerized", lambda: False)
+ monkeypatch.setattr(migration, "_requirements", lambda: pytest.fail("Requirements check"))
+ migration.FrameworkDependencies(None).execute()
diff --git a/tests/test_litellm_sdk.py b/tests/test_litellm_sdk.py
new file mode 100644
index 000000000..0ea5c4937
--- /dev/null
+++ b/tests/test_litellm_sdk.py
@@ -0,0 +1,202 @@
+"""Exercise the installed SDK over loopback HTTP, without provider credentials."""
+
+from collections import deque
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+from threading import Thread
+from types import SimpleNamespace
+
+import pytest
+
+import models
+from helpers.litellm_transport import (
+ LiteLLMTransport,
+ clear_transport_capability_cache,
+ delete_stored_response_ids,
+)
+
+
+TOOL = {
+ "type": "function", "name": "lookup", "description": "Look up a value",
+ "parameters": {"type": "object", "properties": {"q": {"type": "string"}},
+ "required": ["q"], "additionalProperties": False},
+}
+ARGUMENTS = json.dumps({"q": "café"}, ensure_ascii=False)
+USAGE = {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
+
+
+def provider():
+ state = SimpleNamespace(replies=deque(), requests=[])
+
+ class Handler(BaseHTTPRequestHandler):
+ def do_POST(self):
+ body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
+ state.requests.append((self.command, self.path, json.loads(body) if body else {}))
+ status, reply = state.replies.popleft() if state.replies else (500, {"error": "Unexpected request"})
+ streaming = isinstance(reply, str)
+ payload = (reply if streaming else json.dumps(reply)).encode()
+ self.send_response(status)
+ self.send_header("Content-Type", "text/event-stream" if streaming else "application/json")
+ self.send_header("Content-Length", str(len(payload)))
+ self.end_headers()
+ self.wfile.write(payload)
+
+ do_DELETE = do_POST
+
+ def log_message(self, *_args):
+ pass
+
+ clear_transport_capability_cache()
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ thread = Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ state.kwargs = {"api_base": f"http://127.0.0.1:{server.server_port}/v1",
+ "api_key": "test-key", "num_retries": 0, "timeout": 5, "drop_params": True}
+ try:
+ yield state
+ assert not state.replies, "An expected provider request was never sent"
+ finally:
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=5)
+ clear_transport_capability_cache()
+
+
+def sse(events, *, done=False):
+ return "".join(f"data: {json.dumps(event, ensure_ascii=False)}\n\n" for event in events) + (
+ "data: [DONE]\n\n" if done else ""
+ )
+
+
+def chat_reply(stream):
+ base = {"id": "chatcmpl-test", "created": 1, "model": "gpt-4o"}
+ call = {"index": 0, "id": "call_test", "type": "function",
+ "function": {"name": "lookup", "arguments": ARGUMENTS}}
+ if not stream:
+ return {**base, "object": "chat.completion", "usage": USAGE,
+ "choices": [{"index": 0, "finish_reason": "tool_calls",
+ "message": {"role": "assistant", "content": "Working.", "tool_calls": [call]}}]}
+ return sse([
+ {**base, "object": "chat.completion.chunk", "choices": [{"index": 0, "finish_reason": None,
+ "delta": {"role": "assistant", "tool_calls": [{**call, "function": {"name": "lookup", "arguments": ""}}]}}]},
+ {**base, "object": "chat.completion.chunk", "choices": [{"index": 0, "finish_reason": None,
+ "delta": {"tool_calls": [{"index": 0, "function": {"arguments": ARGUMENTS}}]}}]},
+ {**base, "object": "chat.completion.chunk", "choices": [{"index": 0, "finish_reason": "tool_calls", "delta": {}}]},
+ {**base, "object": "chat.completion.chunk", "choices": [], "usage": USAGE},
+ ], done=True)
+
+
+def response_reply(stream):
+ reasoning = {"id": "rs_test", "type": "reasoning", "summary": [], "encrypted_content": "opaque-state"}
+ call = {"id": "fc_test", "type": "function_call", "call_id": "call_test", "name": "lookup",
+ "arguments": ARGUMENTS, "status": "completed"}
+ response = {"id": "resp_test", "object": "response", "created_at": 1, "model": "gpt-4o",
+ "status": "completed", "output": [reasoning, call], "error": None, "incomplete_details": None,
+ "parallel_tool_calls": False, "tools": [TOOL], "tool_choice": "required",
+ "usage": {"input_tokens": 10, "output_tokens": 5, "total_tokens": 15,
+ "input_tokens_details": {"cached_tokens": 0}, "output_tokens_details": {"reasoning_tokens": 2}}}
+ if not stream:
+ return response
+ return sse([
+ {"type": "response.created", "sequence_number": 0, "response": {**response, "status": "in_progress", "output": []}},
+ {"type": "response.output_item.added", "sequence_number": 1, "output_index": 0, "item": reasoning},
+ {"type": "response.output_item.added", "sequence_number": 2, "output_index": 1,
+ "item": {**call, "arguments": "", "status": "in_progress"}},
+ {"type": "response.function_call_arguments.delta", "sequence_number": 3, "output_index": 1,
+ "item_id": "fc_test", "delta": ARGUMENTS},
+ {"type": "response.output_item.done", "sequence_number": 4, "output_index": 1, "item": call},
+ {"type": "response.completed", "sequence_number": 5, "response": response},
+ ])
+
+
[email protected]("async_call", [False, True])
[email protected]("stream", [False, True])
[email protected]("mode", ["chat_completions", "responses"])
+async def test_sdk_tools_usage_and_state_over_http(provider, mode, stream, async_call):
+ native = mode == "responses"
+ provider.replies.append((200, response_reply(stream) if native else chat_reply(stream)))
+ transport = LiteLLMTransport(
+ model="openai/gpt-4o", messages=[{"role": "user", "content": "Look up café"}],
+ kwargs={**provider.kwargs, "a0_api_mode": mode,
+ **({"a0_responses_function_tools": [TOOL]} if native else {})},
+ )
+ if stream:
+ chunks = [chunk async for chunk in transport.astream()] if async_call else list(transport.stream())
+ assert "lookup" in "".join(chunk["response_delta"] for chunk in chunks)
+ elif async_call:
+ await transport.acomplete()
+ else:
+ transport.complete()
+ result = transport.last_result
+ assert result is not None and result.mode == mode
+ assert result.function_calls[0].name == "lookup"
+ assert result.function_calls[0].arguments == {"q": "café"}
+ assert result.function_calls[0].call_id == "call_test"
+ assert result.usage["total_tokens"] == 15
+ method, path, body = provider.requests[0]
+ assert method == "POST" and path == ("/v1/responses" if native else "/v1/chat/completions")
+ assert not any(key.startswith("a0_") or key.startswith("responses_") for key in body)
+ if native:
+ assert result.output_items[0].data["encrypted_content"] == "opaque-state"
+ assert body["tools"][0]["name"] == "lookup"
+ assert body["tool_choice"] == "required" and body["parallel_tool_calls"] is False
+ provider.replies.append((200, response_reply(False)))
+ replay = LiteLLMTransport(
+ model="openai/gpt-4o", messages=[], kwargs={**provider.kwargs, "a0_api_mode": "responses",
+ "previous_response_id": result.response_id,
+ "responses_input_items": [{"type": "function_call_output", "call_id": "call_test", "output": "Found"}]},
+ )
+ await replay.acomplete()
+ assert provider.requests[1][2]["previous_response_id"] == "resp_test"
+ assert provider.requests[1][2]["input"][0]["call_id"] == "call_test"
+ provider.replies.append((200, {"id": "resp_test", "object": "response.deleted", "deleted": True}))
+ assert delete_stored_response_ids([result.response_id], **provider.kwargs) == []
+ assert provider.requests[2][:2] == ("DELETE", "/v1/responses/resp_test")
+ elif stream:
+ assert body["stream_options"]["include_usage"] is True
+
+
+async def test_sdk_responses_fallback_over_http(provider):
+ provider.replies.extend([
+ (404, {"error": {"message": "Responses endpoint not found", "type": "invalid_request_error"}}),
+ (200, chat_reply(False)),
+ ])
+ transport = LiteLLMTransport(model="openai/gpt-4o", messages=[{"role": "user", "content": "Hello"}],
+ kwargs={**provider.kwargs, "a0_api_mode": "responses"})
+ await transport.acomplete()
+ assert [row[1] for row in provider.requests] == ["/v1/responses", "/v1/chat/completions"]
+ assert transport.last_result.mode == "chat_completions"
+
+
+def test_sdk_embedding_batch_over_http(provider):
+ provider.replies.append((200, {"object": "list", "model": "text-embedding-3-small",
+ "data": [{"object": "embedding", "index": i, "embedding": vector}
+ for i, vector in enumerate([[1.0, 0.0], [0.0, 1.0]])],
+ "usage": {"prompt_tokens": 2, "total_tokens": 2}}))
+ wrapper = models.LiteLLMEmbeddingWrapper("text-embedding-3-small", "openai", **provider.kwargs,
+ a0_api_mode="responses")
+ assert wrapper.embed(["first", "second"]) == [[1.0, 0.0], [0.0, 1.0]]
+ assert provider.requests[0][1] == "/v1/embeddings"
+ assert provider.requests[0][2]["input"] == ["first", "second"]
+ assert "a0_api_mode" not in provider.requests[0][2]
+
+
+def test_sdk_anthropic_cache_markers_over_http(provider):
+ provider.replies.append((200, {"id": "msg_test", "type": "message", "role": "assistant",
+ "model": "claude-sonnet-4-5", "content": [{"type": "text", "text": "Hello"}],
+ "stop_reason": "end_turn", "stop_sequence": None, "usage": {"input_tokens": 10, "output_tokens": 1}}))
+ transport = LiteLLMTransport(model="anthropic/claude-sonnet-4-5", messages=[
+ {"role": "system", "content": "Stable instructions"},
+ {"role": "user", "content": "Hello"},
+ {"role": "assistant", "content": [{"type": "text", "text": "Prior answer"}]},
+ {"role": "user", "content": "Continue"},
+ ], kwargs={**provider.kwargs, "api_base": provider.kwargs["api_base"].removesuffix("/v1"),
+ "a0_explicit_prompt_caching": True, "max_tokens": 32})
+ assert transport.complete()["response_delta"] == "Hello"
+ assert provider.requests[0][1] == "/v1/messages"
+ body = provider.requests[0][2]
+ assert body["system"][-1]["cache_control"] == {"type": "ephemeral"}
+ assert body["messages"][1]["content"][-1]["cache_control"] == {"type": "ephemeral"}