Repository navigation
fix(update): keep the Python and the tool environment on self-update - #963
Conversation
keboola-pr-reviewer-bot
left a comment
There was a problem hiding this comment.
Verdict: needs_human (risk 3/5) · profile _default
Self-update command change is sound and failure-safer, but high blast radius warrants a human glance.
Concerns:
src/keboola_agent_cli/services/version_service.py: Self-update command change; Windows path untested, regression can brick installssrc/keboola_agent_cli/services/version_service.py: upgrade_command/recovery shape now omits --force; scripts parsing it may differ
zajca
left a comment
There was a problem hiding this comment.
Automated code review
Reviewed by Opus + Sonnet, full review of 00e3dd4ca7a5.
Opus: Trusted base: 8d00277. The PR changes the self-update command built by build_kbagent_upgrade_command, which kbagent update, the startup auto-update and the deferred Windows helper all use. The new command is uv tool install --reinstall --compile-bytecode --python <sys._base_executable> <spec>. It drops --force, except when kbagent runs from the legacy keboola-agent-cli distribution. The uv recovery command and upgrade_command change the same way. The PR also updates the help text, the CLI manifest, the update_runner.py docstring and gotchas.md, and adjusts the tests.
What I reviewed:
- The full diff and the surrounding code:
version_service.pycommand and recovery builders, the hardlink retry path,APP_NAMEresolution inconstants.py, and the callers inauto_update.py. - The repository guidance from the trusted base (
CLAUDE.md/AGENTS.md). The PR follows it: no version bump, nochangelog.pyentry, and the gotchas section is taggedvNEXT. - How
sys._base_executableresolves, checked locally. It gives the base interpreter for uv tool venvs (the uv-managed minor-version link) and for system-Python venvs. - How uv behaves without
--forcewhen the target executable already exists but no uv tool owns it, checked in a temporary uv tool directory. uv refuses the install. That result is the basis of the one finding.
Tests: the new tests in tests/test_version_service.py would turn red if --force came back on the normal path, if --python were dropped, or if the legacy distribution lost --force. The updated assertions in tests/test_auto_update.py still check the reinstall and extras outcomes. The tests compute the expected interpreter the same way as the production code, which is acceptable for this argv contract. No test covers the case of a kbagent that is not a uv tool while uv is on PATH; see C001.
Compatibility: upgrade_command, the recovery string and the update argv are externally observable and do change. The change is intended and documented. It does break one install path: a pip --user or pipx install of kbagent on a host where uv is on PATH. For that path, neither the self-update nor the printed recovery command can replace the existing kbagent executable any more (C001, non-blocking).
Reuse: the new _uv_update_args helper factors out options that were already inline in build_kbagent_upgrade_command. I found no existing helper with the same responsibility in the trusted base, so there is no duplication.
No blocking issues were found. Apart from C001, I found no actionable correctness, security, compatibility, test or maintainability issues in the review scope.
Sonnet: The trusted base is 8d00277. This PR changes the uv-based self-update command. _uv_update_args() in version_service.py replaces --force --reinstall --compile-bytecode with --reinstall --compile-bytecode --python <sys._base_executable>. The legacy keboola-agent-cli distribution (APP_NAME check) keeps --force. The PR also updates the docstrings in update_runner.py and commands/version.py, plus the CLI manifest and the gotchas reference. I read the whole diff of src, tests, plugins and the manifest against the base. I also checked the frozen-build handling in auto_update.py: PyInstaller builds take a separate notify-only path and never reach this command builder. The recovery command and the hardlink-retry command still build correctly, because the link mode is inserted before the last argument. Repository guidance (AGENTS.md/CLAUDE.md) was not consulted beyond the surrounding code conventions, which the change follows. Tests: the new tests in tests/test_version_service.py assert the command outcome (--force absent, --python equals the base interpreter, --force kept for the legacy APP_NAME) and would fail if _uv_update_args were reverted or the legacy branch were dropped. The updated test_auto_update.py assertions are consistent with the change. Compatibility: the self-update argv, upgrade_command in kbagent --json version, and the recovery command text change, and the PR documents this in gotchas.md. The legacy-tool path keeps --force, and the pip fallback is unchanged, so I found no breaking path. Reuse: no new duplicate functionality; the change extends the existing build_kbagent_upgrade_command. No actionable correctness, security, compatibility, test, or maintainability issues were found in the trusted review scope. I did not review the web/frontend and other files shown by the main...HEAD stat, because they are not part of this PR relative to the base.
No blocking findings were identified.
1 non-blocking note(s): no action required in this pull request
O001 MEDIUM — No --force: the update fails for a kbagent that is not a uv tool when uv is on PATH (confidence: medium, Opus)
src/keboola_agent_cli/services/version_service.py:228
build_kbagent_upgrade_command picks the uv command whenever shutil.which("uv") succeeds. It does not check whether the running kbagent is actually a uv tool. Example: kbagent was installed with pip install --user keboola-cli or with pipx, so ~/.local/bin/kbagent is a pip or pipx entry script, and uv is also on PATH. The command uv tool install --reinstall ... --python <base> keboola-cli @ ... then creates a new tool environment. Because the kbagent executable already exists and no uv receipt owns it, uv stops with error: Executable already exists: kbagent (use --force to overwrite) and removes the new environment. I reproduced this in an isolated UV_TOOL_DIR/UV_TOOL_BIN_DIR with a stand-in executable: the install without --force fails, and the install with --force replaces the executable.
At the base commit, --force overwrote the script, so those installs moved to a uv tool and updated. With this PR:
kbagent updateand every startup auto-update attempt fail for these users.- The printed recovery command fails too.
_recovery_commandreuses the uv argv for uv commands, so it also lacks--force.
The old version keeps working, so no data is lost, but these users are stuck on it. The gotchas text says pip installs keep --force. That is true only when uv is not on PATH.
Possible fixes:
- Keep
--forcewhen the running interpreter is not inside the uv tool directory (for example, checksys.prefixagainstuv tool dir), or detect the uv receipt (uv-receipt.tomlnext tosys.prefix). - At a minimum, add
--forceto the printed recovery command for this case and document the limitation.
🤖 Written by AI: Hermes pr-review (posted from zajca's GitHub account, not by a human)
Why
uv tool install --force --reinstall --compile-bytecode <spec>without--python. When the install failed after uv had removed the tool environment, kbagent was gone. This had two causes:--python, uv selects an interpreter by its own rules. A Windows user installed Python 3.15, and the next update built the environment again on 3.15. PyYAML 6.0.3 has no Windows wheel for 3.15, and its build needs Microsoft C++ Build Tools. The build failed after uv had deleted the old environment.--force, uv 0.10.10 and newer always builds a new tool environment and deletes it when the install fails (Recreate Python environments underuv tool install --forceastral-sh/uv#18399). Any failure after the dependency resolution deletes kbagent, for example a build error or a network error during the download. This also occurs when the Python does not change.What changed
kbagent update, the startup update and the deferred helper on Windows) runsuv tool install --reinstall --compile-bytecode --python <sys._base_executable> <spec>. uv then updates the existing environment and keeps the old version when a download or a build fails. kbagent stays on the Python it was installed with.--forcestays only when kbagent runs from the legacykeboola-agent-clidistribution. Its update installs the new toolkeboola-cli, which takes over thekbagentexecutable of the old tool. uv allows that only with--force.upgrade_commandinkbagent --json versionhave the same form, without--force. The fallback commands for a pip install, and for a host where kbagent finds no uv onPATH, do not change.kbagent update,docs/cli-manifest.json, the module docstring ofupdate_runner.pyand a new section ingotchas.mddescribe the change.sys._base_executablefollows thehomeof the tool environment. For a Python that uv manages, this is the minor-version link (cpython-3.13-…), so the path stays valid after a patch upgrade of that Python, like the environment itself.tests/test_version_service.pyandtests/test_auto_update.pychanged. Two new tests check that the update passes the running interpreter without--force, and that the legacy distribution keeps--force.Checks
make checkpasses.kbagent-like executable that another tool also lists, without--force.sys.base_prefixof the environment with that of the requested interpreter (PythonEnvironment::uses). Sosys._base_executableselects the existing environment there too.