vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-10-21 21:59:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
agent-zero/extensions/python/startup_migration/AGENTS.md
Alessandro b91384f4fb Upgrade LiteLLM and OpenAI with framework startup migration 
Update LiteLLM to 1.104.0, OpenAI to 2.54.0, and python-dotenv to 1.2.2.
Raise shared security floors for aiohttp, anyio, urllib3, filelock, fsspec,
and multidict while retaining the compatible OpenAI 2.x SDK line.

Use the existing startup_migration hook to apply the same requirements to
v2.x Docker instances updating to v2.14. Read versions from requirements.txt,
install only when requirements are unmet, and reuse restart_process() to
load the upgraded SDKs before serving requests. Skip current and non-Docker
environments, bound installation time, and propagate installation failures.

Add installed-SDK HTTP tests for Chat Completions, Responses, streaming,
tools, state, usage, fallback, embeddings, and Anthropic cache markers.
Cover dependency migration, restart behavior, and installation failures.

Validation:
- 70 focused dependency, SDK, and self-update tests passed.
- Docker startup upgraded the v2.0-v2.13 SDK pins and became healthy in
  24 seconds, with exactly one dependency installation and process restart.
- An already-current startup performed no installation or extra restart.
- pip check passed; live Codex Responses and Moonshot Chat Completions
  tasks and follow-ups validated the upgraded SDK versions.
2026-10-07 14:50:32 +02:00

1.8 KiB
Raw Permalink Blame History

Startup Migration Extensions DOX

Purpose

  • Own backend startup migrations.

Ownership

  • Ordered Python files in this folder own idempotent migration steps that run during startup.

Local Contracts

  • 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.

Work Guidance

  • Add migrations only for durable state changes that cannot be handled lazily elsewhere.

Verification

  • Smoke-test startup on a clean checkout and on representative existing user state when practical.

Child DOX Index

No child DOX files.