Agent Zero AI framework
Upgrade LiteLLM and OpenAI with framework startup migration
Alessandrob91384f4fb87
diff --git a/AGENTS.md b/AGENTS.mdindex 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.## Permissionsdiff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.mdindex 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.pynew file mode 100644index 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 outdateddiff --git a/requirements.txt b/requirements.txtindex bd1cbeeee..ef4b7ebbf 100644--- a/requirements.txt+++ b/requirements.txt@@ -20,8 +20,8 @@ langchain-core==0.3.49langchain-community==0.3.19langchain-unstructured==0.1.6liteparse==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.0openai-whisper==20250625lxml_html_clean>=0.4.0 # CVE-2024-52595 fix: XSS CWE-79 CVSS 8.4markdown==3.7@@ -30,7 +30,7 @@ newspaper3k==0.2.8paramiko==3.5.0patchright==1.61.2pypdf==6.0.0-python-dotenv==1.1.0+python-dotenv==1.2.2pytz==2024.2sentence-transformers==3.0.1tiktoken==0.8.0@@ -64,7 +64,12 @@ wsproto>=1.2.0Pillow>=10.2.0 # security floor: heap buffer overflow CWE-122, eval injection CWE-95, DoS CWE-400nltk>=3.9.3 # security floor: RCE CWE-94, code injection CWE-94h11>=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 exhaustioncryptography>=46.0.0 # security floor: insufficient data authenticity CWE-345werkzeug>=3.0.3 # security floor: RCE CWE-94starlette==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 leaksdiff --git a/tests/AGENTS.md b/tests/AGENTS.mdindex 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 Indexdiff --git a/tests/test_framework_dependencies.py b/tests/test_framework_dependencies.pynew file mode 100644index 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()++[email protected]("error", [+ 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.pynew file mode 100644index 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"}