Skip to content

fix(update): keep the Python and the tool environment on self-update - #963

Merged
soustruh merged 1 commit into
mainfrom
self-update-keep-python
Nov 5, 2026
Merged

soustruh merged 1 commit into
mainfrom
self-update-keep-python

Conversation

@soustruh

@soustruh soustruh commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Why

  • The self-update ran 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:
    • Without --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.
    • With --force, uv 0.10.10 and newer always builds a new tool environment and deletes it when the install fails (Recreate Python environments under uv tool install --force astral-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

  • The self-update (kbagent update, the startup update and the deferred helper on Windows) runs uv 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.
  • --force stays only when kbagent runs from the legacy keboola-agent-cli distribution. Its update installs the new tool keboola-cli, which takes over the kbagent executable of the old tool. uv allows that only with --force.
  • The recovery command after a failed uv update and upgrade_command in kbagent --json version have the same form, without --force. The fallback commands for a pip install, and for a host where kbagent finds no uv on PATH, do not change.
  • The help of kbagent update, docs/cli-manifest.json, the module docstring of update_runner.py and a new section in gotchas.md describe the change.
  • sys._base_executable follows the home of 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: the expected commands in tests/test_version_service.py and tests/test_auto_update.py changed. Two new tests check that the update passes the running interpreter without --force, and that the legacy distribution keeps --force.

Checks

  • make check passes.
  • uv behavior, checked in an isolated tool directory with a test package whose build fails. The tool ran on Python 3.12, and the default Python of uv was 3.13. uv versions: 0.2.20, 0.4.0, 0.5.0, 0.6.0, 0.8.0, 0.10.9, 0.10.10 and 0.12.15.
    • New command, all versions: a failed build keeps the old environment and version. An update from 1.0 to 2.0 runs in place on Python 3.12.
    • Old command, all versions: a failed build deletes the environment. With an unchanged default Python, it deletes the environment on 0.2.20, 0.10.10 and 0.12.15, and keeps it on 0.8.0 and 0.10.9.
    • On 0.10.9 and 0.12.15, the new command replaces a kbagent-like executable that another tool also lists, without --force.
  • Not tested on Windows. On Windows, uv compares the sys.base_prefix of the environment with that of the requested interpreter (PythonEnvironment::uses). So sys._base_executable selects the existing environment there too.

@keboola-pr-reviewer-bot keboola-pr-reviewer-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 installs
  • src/keboola_agent_cli/services/version_service.py: upgrade_command/recovery shape now omits --force; scripts parsing it may differ

@zajca zajca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.py command and recovery builders, the hardlink retry path, APP_NAME resolution in constants.py, and the callers in auto_update.py.
  • The repository guidance from the trusted base (CLAUDE.md/AGENTS.md). The PR follows it: no version bump, no changelog.py entry, and the gotchas section is tagged vNEXT.
  • How sys._base_executable resolves, 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 --force when 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 update and every startup auto-update attempt fail for these users.
  • The printed recovery command fails too. _recovery_command reuses 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 --force when the running interpreter is not inside the uv tool directory (for example, check sys.prefix against uv tool dir), or detect the uv receipt (uv-receipt.toml next to sys.prefix).
  • At a minimum, add --force to 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)

@soustruh
soustruh merged commit c2c69f3 into main Nov 5, 2026
5 checks passed
@soustruh
soustruh deleted the self-update-keep-python branch November 5, 2026 14:15
@soustruh soustruh mentioned this pull request Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants