Skip to content

Agent Zero AI framework

Refresh Codex CLI during self-update

Alessandro1410bdcf6c95
diff --git a/docker/run/AGENTS.md b/docker/run/AGENTS.md
index b5607ae69..489df5667 100644
--- a/docker/run/AGENTS.md
+++ b/docker/run/AGENTS.md
@@ -23,6 +23,7 @@
- Runtime startup must ensure `/a0/usr/uploads` exists before supervised services start.
- Runtime startup raises the soft open-file limit toward `A0_NOFILE_LIMIT` (default `65535`) before supervisord starts, bounded by the container hard limit.
- Self-update user-data backups skip Time Travel shadow history under `usr/.time_travel/` and transient Desktop agent state.
+- Successful or already-current self-updates refresh an installed Codex CLI with npm on a best-effort basis; missing CLIs and registry failures must not block Agent Zero startup.
## Work Guidance
diff --git a/docker/run/fs/exe/self_update_manager.py b/docker/run/fs/exe/self_update_manager.py
index 4ae23ce28..51154697b 100644
--- a/docker/run/fs/exe/self_update_manager.py
+++ b/docker/run/fs/exe/self_update_manager.py
@@ -635,6 +635,29 @@ def clean_uv_cache(logger: AttemptLogger) -> None:
logger.log(f"uv cache clean skipped after error: {exc}")
+def refresh_codex_cli(logger: AttemptLogger) -> None:
+ codex_path = shutil.which("codex")
+ if not codex_path:
+ logger.log("Codex CLI not installed, skipping Codex refresh.")
+ return
+
+ npm_path = shutil.which("npm")
+ if not npm_path:
+ logger.log("npm executable not found, skipping Codex refresh.")
+ return
+
+ logger.log("Refreshing the installed Codex CLI after self-update.")
+ try:
+ run_command(
+ [npm_path, "install", "--global", "@openai/codex@latest"],
+ cwd=None,
+ logger=logger,
+ error_message="Failed to refresh the installed Codex CLI.",
+ )
+ except Exception as exc:
+ logger.log(f"Codex CLI refresh skipped after error: {exc}")
+
+
def has_local_rollback_changes(repo_dir: Path) -> bool:
status = git_output(repo_dir, "status", "--porcelain=v1", "--untracked-files=all")
return bool(status.strip())
@@ -1148,6 +1171,7 @@ def execute_pending_update(
logger=logger,
)
if healthy:
+ refresh_codex_cli(logger)
record_result(
status="success",
message=f"Updated Agent Zero to branch {branch}, {resolved_target['target_description']}.",
@@ -1425,6 +1449,7 @@ def docker_run_ui() -> int:
logger.log(
"Requested tag already matches the installed version, skipping file replacement."
)
+ refresh_codex_cli(logger)
record_result(
status="skipped",
message="Requested tag already matches the installed version.",
@@ -1468,8 +1493,11 @@ def main(argv: list[str] | None = None) -> int:
return docker_run_ui()
if args[0] == "trigger-update":
return trigger_update_command(args[1:])
+ if args[0] == "refresh-codex":
+ refresh_codex_cli(AttemptLogger(LOG_FILE))
+ return 0
if args[0] in {"-h", "--help"}:
- print("Usage: self_update_manager.py [docker-run-ui | trigger-update ...]")
+ print("Usage: self_update_manager.py [docker-run-ui | trigger-update ... | refresh-codex]")
return 0
print(f"Unknown command: {args[0]}", file=sys.stderr)
return 1
diff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.md
index fc75b8a8b..d3ffc39a0 100644
--- a/extensions/python/startup_migration/AGENTS.md
+++ b/extensions/python/startup_migration/AGENTS.md
@@ -14,6 +14,7 @@
- Preserve user data and create backups or reversible paths when changing durable state.
- Keep long-running work bounded and observable.
- `_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.
+- 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
diff --git a/extensions/python/startup_migration/_10_self_update_manager.py b/extensions/python/startup_migration/_10_self_update_manager.py
index 8a188d6d0..fff24cc1c 100644
--- a/extensions/python/startup_migration/_10_self_update_manager.py
+++ b/extensions/python/startup_migration/_10_self_update_manager.py
@@ -3,6 +3,8 @@ from __future__ import annotations
import os
import shutil
import stat
+import subprocess
+import sys
from pathlib import Path
from typing import Any
@@ -25,6 +27,8 @@ REQUIRED_RUNTIME_MARKERS = (
"Skipping non-regular usr backup entry",
"def clean_transient_desktop_agent_state(",
"clean_transient_desktop_agent_state(REPO_DIR, logger)",
+ "def refresh_codex_cli(",
+ "refresh_codex_cli(logger)",
)
@@ -33,6 +37,9 @@ class SelfUpdateManagerRuntimeSync(Extension):
result = ensure_self_update_manager_runtime_current()
if result.get("updated"):
PrintStyle.info("Self-update manager runtime synchronized:", result["target"])
+ warning = start_codex_cli_refresh(result["target"])
+ if warning:
+ PrintStyle.warning("Codex CLI refresh could not be started:", warning)
elif result.get("warning"):
PrintStyle.warning("Self-update manager runtime sync skipped:", result["warning"])
@@ -84,6 +91,20 @@ def ensure_self_update_manager_runtime_current(
}
+def start_codex_cli_refresh(manager_path: Path | str) -> str:
+ try:
+ subprocess.Popen(
+ [sys.executable, str(manager_path), "refresh-codex"],
+ stdin=subprocess.DEVNULL,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ start_new_session=True,
+ )
+ except OSError as exc:
+ return str(exc)
+ return ""
+
+
def _missing_required_markers(text: str) -> list[str]:
return [marker for marker in REQUIRED_RUNTIME_MARKERS if marker not in text]
diff --git a/tests/test_self_update_runtime_sync.py b/tests/test_self_update_runtime_sync.py
index 63cea78e8..fc30bba02 100644
--- a/tests/test_self_update_runtime_sync.py
+++ b/tests/test_self_update_runtime_sync.py
@@ -28,8 +28,13 @@ def clean_transient_desktop_agent_state(repo_dir, logger):
return None
+def refresh_codex_cli(logger):
+ return None
+
+
def docker_run_ui():
clean_transient_desktop_agent_state(REPO_DIR, logger)
+ refresh_codex_cli(logger)
"""
@@ -70,6 +75,20 @@ def test_self_update_runtime_sync_accepts_repository_manager_source(tmp_path):
assert target.read_text(encoding="utf-8") == source.read_text(encoding="utf-8")
+def test_self_update_runtime_sync_starts_codex_refresh(monkeypatch, tmp_path):
+ calls = []
+ manager_path = tmp_path / "self_update_manager.py"
+ monkeypatch.setattr(
+ migration.subprocess,
+ "Popen",
+ lambda *args, **kwargs: calls.append((args, kwargs)),
+ )
+
+ assert migration.start_codex_cli_refresh(manager_path) == ""
+ assert calls[0][0][0] == [sys.executable, str(manager_path), "refresh-codex"]
+ assert calls[0][1]["start_new_session"] is True
+
+
def test_self_update_runtime_sync_skips_current_manager(tmp_path):
source = tmp_path / "source_self_update_manager.py"
target = tmp_path / "self_update_manager.py"
diff --git a/tests/test_self_update_tag_filter.py b/tests/test_self_update_tag_filter.py
index 2f351f4ad..f4c2aab34 100644
--- a/tests/test_self_update_tag_filter.py
+++ b/tests/test_self_update_tag_filter.py
@@ -1106,6 +1106,56 @@ def test_self_update_manager_clean_uv_cache_is_best_effort(monkeypatch):
assert any("uv cache clean skipped after error" in message for message in messages)
+def test_self_update_manager_refreshes_installed_codex_best_effort(monkeypatch):
+ manager = load_self_update_manager()
+ commands = []
+ messages = []
+ paths = {"codex": "/usr/local/bin/codex", "npm": "/usr/bin/npm"}
+ monkeypatch.setattr(manager.shutil, "which", paths.get)
+
+ class Logger:
+ def log(self, message=""):
+ messages.append(message)
+
+ def log_block(self, title, content):
+ return None
+
+ def fail_run_command(command, **kwargs):
+ commands.append(command)
+ raise RuntimeError("registry unavailable")
+
+ monkeypatch.setattr(manager, "run_command", fail_run_command)
+
+ manager.refresh_codex_cli(Logger())
+
+ assert commands == [["/usr/bin/npm", "install", "--global", "@openai/codex@latest"]]
+ assert any("Codex CLI refresh skipped after error" in message for message in messages)
+
+
+def test_self_update_manager_skips_codex_refresh_when_not_installed(monkeypatch):
+ manager = load_self_update_manager()
+ commands = []
+ monkeypatch.setattr(manager.shutil, "which", lambda executable: None)
+ monkeypatch.setattr(
+ manager,
+ "run_command",
+ lambda command, **kwargs: commands.append(command),
+ )
+
+ manager.refresh_codex_cli(manager.NullLogger())
+
+ assert commands == []
+
+
+def test_self_update_manager_refresh_codex_command(monkeypatch):
+ manager = load_self_update_manager()
+ loggers = []
+ monkeypatch.setattr(manager, "refresh_codex_cli", lambda logger: loggers.append(logger))
+
+ assert manager.main(["refresh-codex"]) == 0
+ assert len(loggers) == 1
+
+
def test_self_update_manager_latest_on_main_uses_current_major_release(monkeypatch):
manager = load_self_update_manager()
monkeypatch.setattr(