zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/ui/shell.py

@@ -0,0 +1,361 @@
+"""The state the shell's parts share.
+
+:class:`~zettcode.app.ui.app.ZettCodeApp` is assembled from mixins so the class
+itself stays the wiring and the turn loop; each mixin owns one concern — the
+two rows, the keys, the sessions, the notices — and every one of them reads
+the same attributes. This module is that shared surface: annotations plus the
+signatures a part may call on another, never behaviour, so a mixin type-checks
+on its own and the runtime class stays the only implementation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+#: The animation token the effort gauge registers: one token, held for its second
+#: and released when the gauge is over, so the frame loop goes back to sleep.
+EFFORT_TOKEN = "effort"
+
+#: How long a flash stays in the row above the composer: long enough to read a
+#: count of characters, short enough that the next thing typed is not typed into
+#: something the reader is still reading.
+FLASH_SECONDS = 1.5
+
+#: What the conversation says when a request ends having produced nothing: the model was asked and sent back an
+#: empty reply, which the stream reports as a request that completed.
+EMPTY_REPLY = "The model sent back an empty reply. Try again, or check the model and address with /config."
+
+#: What a machine with no ``[[models]]`` entry says for itself. The shell starts anyway — a reader can look through
+#: sessions, change the theme and set a model up — so the line that opens the conversation names the one command
+#: that turns it into a working agent, rather than a start that exits with a message about a file.
+NO_MODEL_START = (
+    "no model is configured yet \u2014 /config adds one (a provider, a model id, and a token); "
+    "nothing else here waits for it"
+)
+
+#: What a prompt typed on such a machine is answered with. It is not an error in the program but in the setup, so
+#: the sentence says how to finish the setup, and the draft is kept so nothing has to be typed again.
+NO_MODEL_ASKED = "no model is configured yet \u2014 /config adds one, then ask again; your words are still in the box"
+
+#: What ``/btw`` says instead, and the difference is the box: a command is submitted and the composer cleared
+#: before its handler runs, so the prompt's "your words are still in the box" would be false there.
+NO_MODEL_QUESTION = "no model is configured yet \u2014 /config adds one; /btw asks it once there is one"
+
+#: Screen name used for a page a command presented; the shell checks it to know
+#: that Ctrl-C and Ctrl-D belong to the page rather than the composer.
+PAGE_SCREEN = "page"
+
+#: Screen name of a question panel. It has its own name because the questions
+#: stack: the model may ask several in one response, and each has to be answered
+#: before the run continues, so the shell needs to tell them from other pages.
+ASK_SCREEN = "ask"
+
+#: Rows the approval panel takes from the bottom of the screen: the question,
+#: up to three lines of command, and the numbered choices.
+APPROVAL_ROWS = 16
+
+#: Rows the "a newer release is out" panel takes: the title, the line saying which index it installs from, the
+#: three rows, and the hint under them.
+UPDATE_ROWS = 9
+
+#: Steering messages one run accepts; the shell caps what a reader can queue
+#: for a single request, and the count resets when a new run starts.
+MAX_STEERING = 8
+
+#: Follow-up messages that may wait at once. They are held by the shell and each takes a row
+#: above the composer, so the list is bounded the way the steering one is.
+MAX_FOLLOW_UPS = 8
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, so the imports stay lazy
+    import asyncio
+    from collections.abc import Sequence
+
+    from zettcode.mentions import MentionRegistry
+    from zettcode.messaging.relayed import Relayed
+    from zettcode.plugin_api.commands import Command
+    from zettcode.plugin_api.pets import Pet
+    from zettcode.plugin_api.state import Activity, UiRow
+    from zettcode.prompt import PromptPart
+    from zettcode.sdk.client import Client
+    from zettcode.sdk.events import QuestionAsked
+    from zettcode.sdk.types import ModelInfo, Usage
+    from zettcode.tui import CompletionPopup, StatusBar, Theme, TuiApp
+    from zettcode.update import UpdateState
+
+    from ..agent.agent import SessionLink, TerminalAgent
+    from ..agent.conversation.effort_gauge import EffortFrame
+    from ..agent.conversation.projection import TranscriptProjector
+    from ..agent.conversation.shimmer import ShimmerFrame
+    from ..agent.conversation.transcript import Transcript
+    from .followups import FollowUp
+    from .gc_policy import CollectorPolicy
+    from .widgets import Composer, FollowUpQueue, PetView, SteeringQueue, TranscriptView, ZettCodeRoot
+
+
+class ShellState:
+    """What one part of the shell may read from the others.
+
+    The attributes are set by :meth:`ZettCodeApp.__init__` and the methods are
+    implemented by one of the mixins; a mixin inherits this class only to be
+    type-checked against the surface it shares with the rest. The one method
+    implemented here is the wait every part of the shell makes before it asks the
+    client for a run.
+    """
+
+    #: The application agent: the only channel to the conversation. The shell sets it once; a mixin reads it.
+    @property
+    def agent(self) -> TerminalAgent:
+        raise NotImplementedError("the shell sets its agent; a mixin only reads it")
+
+    #: The SDK client over that agent: what the shell asks of the agent goes through it as it moves off the agent.
+    @property
+    def client(self) -> Client:
+        raise NotImplementedError("the shell sets its client; a mixin only reads it")
+
+    #: The mounted widget tree and the host services it offers.
+    app: TuiApp
+
+    #: The conversation model every view reads.
+    @property
+    def transcript(self) -> Transcript:
+        raise NotImplementedError("the shell sets its transcript; a mixin only reads it")
+
+    #: The scrollable transcript, and the composer with its completion menu.
+    view: TranscriptView
+    composer: Composer
+    completions: CompletionPopup
+    #: Messages queued to steer the running turn, and the ones held to follow it.
+    steering: SteeringQueue
+    follow_ups: FollowUpQueue
+    #: The two rows the plugin segments fill.
+    header: StatusBar
+    status: StatusBar
+    #: The event projector that fills the transcript, and the root widget.
+    projector: TranscriptProjector
+    root: ZettCodeRoot
+    #: The line to the other sessions, or ``None`` when sessions are switched off.
+    messenger: SessionLink | None
+    #: The merged slash commands and the ``@`` resource registry.
+    commands: tuple[Command, ...]
+    mentions: MentionRegistry
+
+    async def _wait_for_client(self) -> None:
+        """Wait for a run the shell did not start to give the client back.
+
+        A plugin that asks the model for itself — a recap, a notification — takes the client's one run slot and the
+        shell's busy flag knows nothing about it. A turn, a side question, a continue or a fork that started in that
+        window was refused with "a run is already in progress on this client", which a reader saw most often when
+        another session's message arrived while a recap was being written. The reader asked for the work either way, so
+        it waits for the slot; the ask it waits for is one model call, and Ctrl-C stops the wait with everything else.
+
+        Two things it is not for. A rename: `Session.rename` checks the slot only when the name would switch
+        conversations, so a title beside a run needs nothing from here. And a request of the shell's own: a command
+        taken while one runs would hang.
+        """
+        while self.client.busy:
+            await asyncio.sleep(0.05)
+
+    #: The palette in force before the ``/theme`` menu started showing others, or ``None`` when nothing is previewed.
+    _theme_before: Theme | None
+    #: The pet in front of the one the ``/pet`` menu is previewing, or ``None`` when nothing is previewed.
+    _pet_before: Pet | None
+    #: The pet over the conversation.
+    pet: PetView
+    #: The command whose menu is showing its words as it is walked (see ``Command.preview``).
+    _previewing: Command | None
+    #: The plugin rows, in paint order.
+    _plugin_rows: tuple[UiRow, ...]
+    #: What the status line shows: the shell's state and a one-off note.
+    _activity: Activity
+    _note: str | None
+    #: The active session's title, if the store has one.
+    _session_title: str | None
+    #: Cumulative token counters for the active session.
+    _usage: Usage
+    #: Whether a turn or a command is in flight.
+    _busy: bool
+    #: When the garbage collector may run: while work is in flight, and not while the reader types.
+    collector: CollectorPolicy
+    #: Steering messages queued for this run, and how many were queued in all.
+    _steering: list[str]
+    #: What each queued steering message was made of, in step with :attr:`_steering`: the text the
+    #: agent will report it by when it adopts it, and the parts it was sent as.
+    _steering_meta: list[tuple[str, tuple[PromptPart, ...]]]
+    _steering_sent: int
+    #: The follow-ups waiting in send order, the highlighted one, and the slot a message
+    #: taken out for editing will return to.
+    _follow_ups: list[FollowUp]
+    _follow_up_selected: int | None
+    _editing_slot: int | None
+    #: Whether the list is held: a request was stopped or failed with follow-ups waiting, and
+    #: no reply has completed since.
+    _follow_ups_held: bool
+    #: Whether the work in flight is a turn, which can be steered, rather than a command.
+    _turn_running: bool
+    #: Whether a command handed over work that is still being awaited (`CommandResult.run`).
+    _command_working: bool
+    #: The in-flight request that names a session, if any.
+    _title_task: asyncio.Task[None] | None
+    #: The in-flight re-measure of a context figure, if any.
+    _measure_task: asyncio.Task[None] | None
+    #: The in-flight release check or upgrade, if any.
+    _update_task: asyncio.Task[None] | None
+    #: Whether an upgrade is installing now: the composer takes nothing until it is done, since the code it would
+    #: run is being replaced under it.
+    _updating: bool
+    #: A short-lived message for the row above the composer: its text and the
+    #: moment it stops being true.
+    _flash: tuple[str, float, str] | None
+    #: The effort switch being animated: the level it came from, the level it is
+    #: reaching, and the moment it started.
+    _effort_animation: tuple[str, str, float] | None
+    #: The question the model is waiting on, while its panel is up.
+    _asks: list[QuestionAsked]
+    #: The turn or command currently in flight, if any.
+    _task: asyncio.Task[None] | None
+
+    def close_page(self) -> None:
+        """Close the page a command presented."""
+
+    @property
+    def model(self) -> ModelInfo | None:
+        """Return the model the next request would use, or ``None`` on a machine with none configured yet.
+
+        The shell paints with ``None`` — the header says ``no model``, the counters have no window to measure
+        against — and only a request insists on one. :attr:`client.model` is that insisting reader.
+        """
+        return self.client.active_model
+
+    def change_model(self, name: ModelInfo | str) -> ModelInfo:
+        """Switch models and announce the change in the transcript."""
+        raise NotImplementedError
+
+    def _warm_runtime(self) -> None:
+        """Start the runtime's provider and imports behind the frame, once there is a model to build one from."""
+        raise NotImplementedError
+
+    async def resume_session(self, session_id: str) -> None:
+        """Restore a stored session behind the interface rather than in front of it."""
+
+    def _set_busy(self, busy: bool) -> None:
+        """Track in-flight work and keep the frame loop alive while it runs."""
+
+    def _start_next_command(self) -> None:
+        """Run the command that was typed while the finished request was busy."""
+
+    def _return_follow_ups_to_draft(self) -> None:
+        """Hand the held follow-ups back as text, because their conversation is over."""
+
+    @property
+    def _follow_up_selecting(self) -> bool:
+        """Return whether a follow-up is highlighted."""
+        return False
+
+    def _select_follow_up(self, step: int) -> None:
+        """Move the follow-up highlight."""
+
+    def _deselect_follow_up(self) -> None:
+        """Take the follow-up highlight off."""
+
+    def _move_follow_up(self, step: int) -> None:
+        """Swap the highlighted follow-up with its neighbour."""
+
+    def _edit_follow_up(self) -> bool:
+        """Take the highlighted follow-up out and into the composer."""
+        return False
+
+    def _delete_follow_up(self) -> None:
+        """Remove the highlighted follow-up from the list."""
+
+    def _steer_follow_up(self) -> bool:
+        """Send the highlighted follow-up to the running request as steering."""
+        raise NotImplementedError
+
+    def _queue_steering(self, value: str, key: str | None = None, parts: Sequence[PromptPart] = ()) -> None:
+        """Show one message waiting for the agent to adopt it."""
+
+    def _clear_steering(self) -> None:
+        """Drop the steering list."""
+
+    def _refuse_busy(self) -> None:
+        """Tell the reader a draft cannot be taken while a request runs."""
+
+    def _refresh_completions(self) -> None:
+        """Mirror the composer's slash-command candidates into the menu."""
+
+    async def _run_prompt(
+        self,
+        prompt: str,
+        parts: Sequence[PromptPart] = (),
+        *,
+        instructions: str | None = None,
+        relayed: Relayed | None = None,
+        advance: bool = True,
+    ) -> None:
+        """Stream one agent turn."""
+
+    def _sync_messaging(self) -> None:
+        """Tell the other sessions what this one is now."""
+
+    def _sync_lock(self) -> None:
+        """Make the composer and the messaging agree with who holds the active session's lock."""
+
+    def _start_next_relayed(self) -> bool:
+        """Start the oldest message another session sent, if one waits and nothing runs."""
+        return False
+
+    def _steer_blocked(self) -> str | None:
+        """Return why the work in flight cannot be steered, or ``None`` when it can."""
+        return None
+
+    def _settle_relayed_steering(self) -> None:
+        """Hand messages a finished request never adopted to the inbox, so they still get a turn."""
+
+    async def run_continue(self) -> None:
+        """Pick up the interrupted request where it stopped."""
+
+    def submit(self, value: str, *, command: bool | None = None) -> bool | None:
+        """Start a turn, steer the running one, or run a slash command (``command``: whether the draft is one)."""
+
+    async def prompt(self, text: str, *, shown: str | None = None, cache: str | None = None) -> bool:
+        """Run ``text`` as one turn, as if the reader had typed it; whether one was started and has ended."""
+        return False
+
+    def stop_working_command(self) -> bool:
+        """Stop a command that handed over work, as Escape does; whether one was working."""
+        return False
+
+    def flash(self, message: str, *, seconds: float = FLASH_SECONDS, level: str = "info") -> None:
+        """Say something in the row above the composer, for a few seconds."""
+
+    def change_permission(self, name: str, *, remember: bool = True) -> str:
+        """Set how much of the shell may run unasked, and announce the change."""
+        return name
+
+    def start_effort_animation(self, previous: str, current: str) -> None:
+        """Animate the effort slot of the header for a second."""
+
+    def _effort_gauge(self) -> EffortFrame | ShimmerFrame | None:
+        """Return the effort gauge for this paint, or None when the switch is over."""
+
+    def settle_effort_animation(self) -> None:
+        """Repaint while an effort switch animates, and release its token at the end."""
+
+    def notify(self, message: str, *, level: str = "info") -> None:
+        """Show a one-line toast."""
+
+    def _remeasure_context_later(self) -> None:
+        """Measure the context again, when a figure needs replacing."""
+
+    def _cancel_ask(self, question: QuestionAsked) -> None:
+        """Decline one question the model is waiting on, and close its panel."""
+
+    def start_update_check(self) -> asyncio.Task[None] | None:
+        """Ask the index about newer releases in the background."""
+
+    def offer_update(self) -> UpdateState | None:
+        """Show the panel a stored newer version asks for, if there is one."""
+
+    def _refresh_tasks(self) -> None:
+        """Mirror the agent's plan into the panel above the composer."""

zettcode/app/ui/turns.py

@@ -0,0 +1,115 @@
+"""What the shell hands the SDK to run a turn, and how it words a turn that failed.
+
+The composer's draft is a list of parts (text, pictures, and ``@`` references as chips); the SDK takes text and
+pictures and resolves the references itself, with the registry the composer completed them from. A failed run reaches
+the shell as an SDK error whose message is already worded, so the only thing left to add is whether trying again may
+help.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Sequence
+
+from zettcode.error_text import CONTINUE_HINT, failure_text
+from zettcode.plugin_api.state import TurnContext, TurnSegment
+from zettcode.prompt import MentionPart, PromptPart
+from zettcode.sdk.errors import RunError, SessionBusyError
+from zettcode.sdk.events import AnyEvent, ToolFinished, ToolStarted
+from zettcode.sdk.types import Image, TaskInfo, Usage
+
+__all__ = [
+    "RUN_IN_PROGRESS",
+    "TurnTally",
+    "failure_line",
+    "plan_rows",
+    "prompt_pieces",
+    "turn_parts",
+]
+
+
+class TurnTally:
+    """What one request spent, kept while it runs so the line it ends on can say.
+
+    The tokens and model calls are the session's usage after the request less its usage before, so they are right
+    for a request that failed or was stopped as well (the calls that finished are counted). The tool calls are counted
+    from the events, because the session keeps no per-request tally of them. It holds numbers; the items of the
+    line (``turn_parts``) say how they read.
+    """
+
+    def __init__(self, before: Usage) -> None:
+        """Start counting from the session's usage as it is now."""
+        self._before = before
+        self.tools = 0
+        self.failed = 0
+
+    def see(self, event: AnyEvent) -> None:
+        """Count a tool the model started, and one that failed (a question the reader cancelled is skipped, not failed)."""
+        if isinstance(event, ToolStarted):
+            self.tools += 1
+        elif isinstance(event, ToolFinished) and not event.ok and not event.skipped:
+            self.failed += 1
+
+    def context(self, now: Usage, *, label: str, seconds: float, clock: str) -> TurnContext:
+        """Return what the request came to, given the session's usage now, how it ended, how long it took and when."""
+        return TurnContext(label, seconds, clock, now.since(self._before), self.tools, self.failed)
+
+
+def turn_parts(segments: Sequence[TurnSegment], context: TurnContext, hidden: Collection[str]) -> tuple[str, ...]:
+    """Return the items of the line a request ends on: each shown segment's text, in order.
+
+    A segment the reader switched off is not asked. One that has nothing to say, or that raises, is left out: a
+    plugin's mistake costs its own item and never the line.
+    """
+    parts: list[str] = []
+    for segment in segments:
+        if segment.name in hidden:
+            continue
+        try:
+            text = segment.builder(context)
+        except Exception:  # noqa: BLE001 - a plugin's item must not take the line down with it
+            continue
+        if text:
+            parts.append(str(text))
+    return tuple(parts)
+
+
+def prompt_pieces(parts: Sequence[PromptPart]) -> list[str | Image]:
+    """Return a draft's parts as the text and pictures the SDK takes, in the order they were written.
+
+    A reference is its token again: the SDK splits the text at the tokens, as the composer did to make the chips.
+    """
+    pieces: list[str | Image] = []
+    for part in parts:
+        if isinstance(part, str):
+            pieces.append(part)
+        elif isinstance(part, MentionPart):
+            pieces.append(part.token)
+        else:
+            data, media_type = part
+            pieces.append(Image(data, media_type))
+    return pieces
+
+
+#: What a run the client refused because another one holds it is said as, in a terminal. The SDK's own sentence tells
+#: a program to leave an ``async with`` block or await ``aclose()``, which is a remedy a reader cannot use; the one
+#: thing that helps is that it will be free in a moment.
+RUN_IN_PROGRESS = "another run is finishing; try again in a moment"
+
+
+def failure_line(error: BaseException) -> str:
+    """Return the line a failed turn is shown as: what failed, and ``/continue`` when trying again may work.
+
+    An SDK run error already carries the sentence, and says whether the failure was the provider's or the network's;
+    anything else is worded here, as it always was.
+    """
+    if isinstance(error, SessionBusyError):
+        return f"error: {RUN_IN_PROGRESS}"
+    if isinstance(error, RunError):
+        text = f"error: {error}"
+        return f"{text.rstrip('.')}. {CONTINUE_HINT}" if error.retryable else text
+    return failure_text(error)
+
+
+def plan_rows(tasks: Sequence[TaskInfo]) -> tuple[tuple[str, str], ...]:
+    """Return the model's plan as the (status, content) rows the task panel and the status line draw."""
+    return tuple((task.status, task.content) for task in tasks)

zettcode/app/ui/updating.py

@@ -0,0 +1,204 @@
+"""The background release check, and the panel that offers what it found.
+
+The check is deliberately not part of the start: it is a task started beside the
+first frame, and the panel is drawn from the *file* the last check left, so a
+start never waits on the network to decide what to paint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from pathlib import Path
+
+from zettcode.tui import Screen
+from zettcode.update import (
+    UpdateState,
+    check_for_update,
+    display_command,
+    fetch_latest,
+    in_background,
+    installed_version,
+    is_newer,
+    read_state,
+    record_install,
+    run_upgrade,
+    running_from,
+    upgrade_command,
+    write_state,
+)
+from zettcode.version import __version__
+
+from .shell import PAGE_SCREEN, UPDATE_ROWS, ShellState
+from .widgets import LATER, UPGRADE, UpdatePage, bottom_panel
+
+
+class UpdateMixin(ShellState):
+    """Offer a newer release, once, until the reader skips it or installs it."""
+
+    def start_update_check(self) -> asyncio.Task[None] | None:
+        """Ask PyPI in the background, unless the configuration turns it off."""
+        if not self.agent.runtime.config.update_enabled:
+            return None
+        self._update_task = asyncio.ensure_future(self._check_for_update())
+        return self._update_task
+
+    async def _check_for_update(self) -> None:
+        """Refresh the stored state; a failure means "no news", never an error."""
+        await check_for_update(self.agent.runtime.config.update_file)
+
+    def offer_update(self) -> UpdateState | None:
+        """Show the panel a stored newer version asks for, if there is one."""
+        if not self.agent.runtime.config.update_enabled:
+            return None
+        path = self.agent.runtime.config.update_file
+        state = read_state(path)
+        shadow = state.shadowed_by(__version__)
+        if shadow is not None:
+            self._explain_shadow(state, shadow, path)
+            return None
+        latest = state.offer(__version__)
+        if latest is None:
+            return None
+        command = upgrade_command()
+        page = UpdatePage(latest, __version__, command, on_choice=lambda choice: self._answer_update(choice, latest))
+        self.app.push_screen(Screen(bottom_panel(page, rows=UPDATE_ROWS), name=PAGE_SCREEN, modal=True))
+        self.app.request_layout()
+        return state
+
+    def _explain_shadow(self, state: UpdateState, installed: str, path: Path) -> None:
+        """Say, once, that an upgrade worked but is not what is running, instead of offering it again.
+
+        Offering the upgrade a second time would change nothing — it is installed — and would look
+        exactly like an upgrade that never happened. What is useful is where the running code is
+        coming from. The explanation is recorded as given, so the next start is quiet about it.
+        """
+        if state.noted == installed:
+            return
+        self.transcript.notice(
+            f"ZettCode {installed} is installed, but this session runs {__version__} from {running_from()}: "
+            "something else is supplying the code (an editable checkout, PYTHONPATH?), so upgrading again "
+            "would not change it"
+        )
+        try:
+            write_state(replace(state, noted=installed), path)
+        except OSError:
+            pass  # said again next start, which is the right failure for a note
+
+    def _answer_update(self, choice: str, latest: str) -> None:
+        """Act on the panel: upgrade, forget this version, or ask again later."""
+        self.close_page()
+        if choice == UPGRADE:
+            self._update_task = asyncio.ensure_future(self._run_upgrade(latest))
+            return
+        if choice == LATER:
+            # Nothing is written: the next start reads the same file and asks
+            # again, which is the whole difference between this and skipping.
+            return
+        path = self.agent.runtime.config.update_file
+        write_state(replace(read_state(path), skipped=latest), path)
+        self.transcript.notice(f"skipping ZettCode {latest}: the next release will be offered")
+
+    async def _run_upgrade(self, latest: str) -> None:
+        """Install the newer release in the background, check that it is there, and report which.
+
+        A package manager exiting 0 is not an upgrade: ``uv tool upgrade`` answers "Nothing to
+        upgrade" with 0, and a pip whose index has not listed the release yet answers "already
+        satisfied" with 0. So the version is read back from the interpreter that was upgraded, and
+        only that is believed: it is what the notice says, and it is what is written to the file the
+        next start reads. An upgrade that left the old version is reported as that, with the way to
+        try again, and writes nothing, so it is offered again.
+
+        The running process keeps the code it started with, so the notice says what the reader has
+        to do about it — restart — rather than implying the window is already the new version.
+
+        The window takes no input while this runs: the installation is being replaced under the process that would be
+        answering, so the lock is taken before anything else — including the index read below, which can take the
+        request timeout — and `submit`, a message from another session and `^D` all find it.
+
+        The version the panel offered is read from the index again first: the file it came from is written by a check
+        that may be hours old, and what an install is measured against should be what PyPI says now, not what a
+        mirror wrote earlier. An index that now names nothing newer than this process means there is nothing to
+        install, and the running version is never replaced by one that is not newer.
+        """
+        command = upgrade_command()
+        self._begin_update()
+        try:
+            offered = latest
+            latest = await self._fresh(offered)
+            if not is_newer(latest, __version__):
+                self.transcript.notice(
+                    f"PyPI names {latest}, which is not newer than the {__version__} running here: nothing installed"
+                )
+                return
+            if latest != offered:
+                self.transcript.notice(f"PyPI now names {latest}, not the {offered} the panel showed")
+            await self._install(command, latest)
+        finally:
+            self._end_update()
+
+    def _begin_update(self) -> None:
+        """Take the window for the install: the flag, the composer's lock and the line that explains it."""
+        self._updating = True
+        self._sync_lock()
+        self.transcript.notice("updating ZettCode \u2014 this window takes no input until it is done")
+        self.app.invalidate()
+
+    def _end_update(self) -> None:
+        """Give the window back, whatever became of the install."""
+        self._updating = False
+        self._sync_lock()
+
+    async def _fresh(self, stored: str) -> str:
+        """Return the newest version the index names now, or ``stored`` when it cannot be asked.
+
+        What is in the update file is a note from the last check, and the check may have been made in another
+        process, on another day, against an answer that has since changed. The index is asked here, at the moment the
+        reader chose to install, and the stored version is only the fallback for an offline machine.
+        """
+        try:
+            return await in_background(fetch_latest)
+        except Exception:  # noqa: BLE001 - offline, a proxy, an odd answer: install what we thought, then measure
+            return stored
+
+    async def _install(self, command: tuple[str, ...], latest: str) -> None:
+        """Run the package manager and report what it left behind."""
+        ok, output = await run_upgrade(command)
+        if not ok:
+            reason = output.splitlines()[-1] if output else "no output"
+            self.transcript.error(f"upgrade failed: {reason}")
+            self.transcript.notice(f"run it yourself: {display_command(command)}")
+            return
+        installed = await installed_version()
+        if installed is None:
+            self.transcript.notice(
+                f"the upgrade ran, but the installed version could not be read back — restart and check "
+                f"with `zettcode --version`; if it is not {latest}: {display_command(command)}"
+            )
+            return
+        if is_newer(latest, installed):
+            self.transcript.error(f"the upgrade ran, but ZettCode is still {installed}, not {latest}")
+            self.transcript.notice(
+                f"the release may be yanked, or the installer may have been pinned to {installed}: "
+                f"try `uv tool install zettcode@latest`, or {display_command(command)}"
+            )
+            return
+        try:
+            record_install(self.agent.runtime.config.update_file, installed)
+        except OSError:
+            pass  # the install happened; failing to write it down must not make it look as if it had not
+        self.transcript.notice(f"ZettCode {installed} installed — restart to use it")
+        self.notify("upgrade finished", level="success")
+
+    async def _stop_update_task(self) -> None:
+        """Drop a check or upgrade still in flight when the app exits.
+
+        Nobody is left to read the answer, and the request behind it may be
+        waiting on a slow index: cancelling the await is what keeps a quit from
+        holding the terminal for as long as that takes.
+        """
+        task, self._update_task = self._update_task, None
+        if task is None or task.done():
+            return
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)