zettcode 0.1.12__tar.gz → 0.2.0__tar.gz

{zettcode-0.1.12 → zettcode-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.12
+Version: 0.2.0
 Summary: A focused terminal coding agent powered by zett-agent
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
@@ -35,7 +35,7 @@ Requires-Dist: truststore<1,>=0.10
 Requires-Dist: uvicorn<1,>=0.35
 Requires-Dist: wcwidth<1,>=0.2
 Requires-Dist: websockets<17,>=15
-Requires-Dist: zett-agent<0.3,>=0.2.0
+Requires-Dist: zett-agent<0.3,>=0.2.1
 Description-Content-Type: text/markdown
 
 # ZettCode

{zettcode-0.1.12 → zettcode-0.2.0}/pyproject.toml

@@ -58,7 +58,7 @@ dependencies = [
   # than it did. An exact pin would make zettcode fight every other tool that
   # shares the dependency — including an upgrade of zett-agent itself, which pip
   # would downgrade to satisfy it.
-  "zett-agent>=0.2.0,<0.3",
+  "zett-agent>=0.2.1,<0.3",
 ]
 
 [project.scripts]

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/__init__.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 #: The one place the version is written. ``pyproject.toml`` reads it from here
 #: and the release workflow checks the tag against it, so a bump is one edit.
-__version__ = "0.1.12"
+__version__ = "0.2.0"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/agent/conversation/entries.py

@@ -243,10 +243,16 @@ class ToolEntry(TimedEntry):
 class ReadEntry(ToolEntry):
     """A file that was read: its body is source code, drawn as the language it is.
 
-    ``language`` names the scanner for the output, or is ``None`` for a file that is not code.
+    ``language`` names the scanner for the output, or is ``None`` for a file that is not code. ``lines`` is how many
+    lines came back, once a completed read has one; it is a field of the row rather than part of its title, so the
+    title being restated or cut at the width cannot lose it. ``picture`` marks a path that looks like a picture — the suffix the read tool
+    sends as an image — since a row is opened from the arguments, before the result exists; a file whose content is an
+    image under another name is counted as text until the result itself says otherwise.
     """
 
     language: str | None = None
+    lines: int | None = None
+    picture: bool = False
 
 
 @dataclass(slots=True, kw_only=True)

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/agent/conversation/presenters.py

@@ -680,10 +680,21 @@ class SessionMessagePresenter(ToolPresenter[MessageEntry]):
 
 
 class ReadPresenter(ToolPresenter[ReadEntry]):
-    """A file that was read: the body is highlighted as the language the file is in."""
+    """A file that was read: the body is highlighted as the language the file is in, and the row says how much."""
 
     entry_type = ReadEntry
 
+    def after_title(self, entry: ReadEntry, theme: Theme) -> list[Span]:
+        """Say how many lines came back, beside the title rather than inside it.
+
+        A field of the row survives what a title does not: `restate_tool` rewrites the title from the arguments, and
+        the count is drawn from the entry, the way an edit's ``+N -N`` is. A row too narrow for the title and the
+        count together cuts the count, as it cuts any tail — an edit's counts go the same way.
+        """
+        if entry.lines is None:
+            return []
+        return [Span(f" \u00b7 {entry.lines} line" + ("" if entry.lines == 1 else "s"), Style(foreground=theme.subtle))]
+
     def body_lines(self, entry: ReadEntry, width: int, theme: Theme, muted: Style) -> list[TextLine]:
         """Show the output as source code when the file is."""
         return self.output_lines(entry, width, theme, muted, language=entry.language)

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/agent/conversation/rendering.py

@@ -33,7 +33,7 @@ from pathlib import Path
 from zettcode.tui import ELLIPSIS, SEPARATOR
 from zettcode.tui.render import GENERIC, language_for
 
-from .entries import DeleteEntry, EditEntry, MessageEntry, ReadEntry, ToolEntry, WriteEntry
+from .entries import DeleteEntry, EditEntry, EntryStatus, MessageEntry, ReadEntry, ToolEntry, WriteEntry
 from .text import DECLINED_NOTE, limit_output
 
 #: Output kinds the chain shapes; a link claims one or more of them.
@@ -41,6 +41,22 @@ TOOL = "tool"
 THINKING = "thinking"
 ANSWER = "answer"
 
+#: Suffixes that look like a picture, copied from the read tool's accepted set: a row is opened from the arguments,
+#: before the result exists, so the suffix is all it has. The durable answer is a boolean on the finished event, taken
+#: from the result's own content — see :func:`is_picture_path`.
+PICTURE_SUFFIXES = frozenset({".png", ".jpg", ".jpeg", ".gif", ".webp"})
+
+
+def is_picture_path(path: str) -> bool:
+    """Return whether ``path`` looks like a picture by its suffix.
+
+    A guess, and named like one: the read tool decides by the file's signature, so a PNG copied to ``.bin`` is counted
+    as text and a text file named ``notes.png`` is not counted. Both are a line about a row nobody is reading closely;
+    the exact answer needs the boolean the result will carry (see :data:`PICTURE_SUFFIXES`).
+    """
+    return Path(path).suffix.lower() in PICTURE_SUFFIXES
+
+
 #: The hint a bounded read leaves behind; it is advice for the model, not the
 #: reader, and the row already shows the text it applies to.
 CONTINUATION = re.compile(r"\n?\.\.\. \[(?:line truncated|more lines)[^\]]*\]\s*\Z")
@@ -128,6 +144,16 @@ class RenderHandler(ABC):
         """Return the text under a tool row; only a tool link changes this."""
         return output
 
+    def finished(self, entry: ToolEntry, text: str, status: EntryStatus) -> None:
+        """Adjust a row now that its result is in — a count, a size — and change nothing by default.
+
+        Args:
+            entry: The row, whose body is already set and bounded.
+            text: The body as it came back, after :meth:`body` shaped it and before it was bounded.
+            status: Whether the call completed, failed or was skipped: a row may only count what worked.
+        """
+        return None
+
     def text(self, text: str, *, opening: bool) -> str:
         """Return one streamed fragment, unchanged unless a link shapes it.
 
@@ -183,6 +209,12 @@ class Renderers:
         handler = self._claim(TOOL, name)
         return output if handler is None else handler.body(name, output)
 
+    def finished(self, entry: ToolEntry, text: str, status: EntryStatus) -> None:
+        """Let the claiming link adjust a row once its result is in."""
+        handler = self._claim(TOOL, entry.tool)
+        if handler is not None:
+            handler.finished(entry, text, status)
+
     def text(self, kind: str, text: str, *, opening: bool = False) -> str:
         """Return one streamed fragment of ``kind``, shaped by the claiming link."""
         handler = self._claim(kind)
@@ -369,16 +401,34 @@ class ReadTool(ToolHandler):
     def open_tool(
         self, name: str, arguments: Mapping[str, object], *, id: int, call_id: str, started_at: float
     ) -> ToolEntry:
-        """A read row, which knows the language its body is in."""
+        """A read row, which knows the language its body is in, and whether the file is a picture."""
         row = self.describe(name, arguments)
+        path = argument(arguments, "path")
         return ReadEntry(
-            id=id, call_id=call_id, tool=name, title=row.title, language=row.language, started_at=started_at
+            id=id,
+            call_id=call_id,
+            tool=name,
+            title=row.title,
+            language=row.language,
+            picture=is_picture_path(path),
+            started_at=started_at,
         )
 
     def body(self, name: str, output: str) -> str:
         """Drop the continuation hint; the row bounds the text it applies to."""
         return CONTINUATION.sub("", output).rstrip()
 
+    def finished(self, entry: ToolEntry, text: str, status: EntryStatus) -> None:
+        """Count what the read returned, on the row, if it returned text and the call worked.
+
+        The count is of what came back — a range asked for is not the same number — and of the whole of it, not of
+        the preview the row keeps, so a read past the output limit is counted in full. A picture carries no lines,
+        and a failed call's body is the error message rather than the file, so neither is counted.
+        """
+        if status is not EntryStatus.COMPLETED or not isinstance(entry, ReadEntry) or entry.picture:
+            return
+        entry.lines = len(text.splitlines())
+
 
 class WriteTool(ToolHandler):
     """``write_file``: the file being written."""
@@ -631,6 +681,33 @@ class MessageTool(ToolHandler):
         )
 
 
+class NamespacedTool(ToolHandler):
+    """A tool whose name carries where it came from: ``server__tool``, so the row names the server.
+
+    The server is part of what the call was: the same ``search`` in two servers is two different tools, with
+    different reach and different answers, and a row that drops the server makes them look like one.
+
+    The name is all a renderer knows, so the row says what the name says — ``github/create_issue`` — and not that
+    the tool speaks MCP: a plugin registers a namespaced name of its own with the same shape, and the runtime does
+    not mark its remote tools here. A name without both parts is shown as it arrived.
+    """
+
+    def handles(self, kind: str, name: str = "") -> bool:
+        """Claim a namespaced name that no earlier link claimed."""
+        return kind == TOOL and "__" in name.strip("_") and not name.startswith("__")
+
+    def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
+        """Show ``server/tool``, so the row names where the capability came from.
+
+        The runtime names a remote tool ``<server>__<tool>``; a name that prefixed the family with ``mcp`` —
+        ``mcp__github__create_issue`` — is read the same way, and one without both parts keeps its own name.
+        """
+        remote = name[5:] if name.startswith("mcp__") else name
+        server, _, tool = remote.partition("__")
+        label = f"{server}/{tool}" if server and tool else name
+        return ToolRow(f"{label} {summarise(arguments)}".rstrip())
+
+
 class FallbackTool(ToolHandler):
     """Anything no other link claims: its name and flat arguments, never JSON."""
 
@@ -639,15 +716,8 @@ class FallbackTool(ToolHandler):
         return kind == TOOL
 
     def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
-        """Show ``name key=value`` so an unknown tool still reads as a sentence.
-
-        An MCP tool is namespaced ``<server>__<tool>``; the server is worth
-        keeping because it says where the capability comes from, but it reads
-        better after the tool than in front of it.
-        """
-        server, _, tool = name.partition("__")
-        label = f"{tool} (via {server})" if tool else name
-        return ToolRow(f"{label} {summarise(arguments)}".rstrip())
+        """Show ``name key=value`` so an unknown tool still reads as a sentence."""
+        return ToolRow(f"{name} {summarise(arguments)}".rstrip())
 
 
 class ReasoningHandler(RenderHandler):
@@ -705,6 +775,7 @@ DEFAULT_RENDERERS = Renderers(
         SkillTool(),
         TaskTool(),
         MessageTool(),
+        NamespacedTool(),
         FallbackTool(),
         ReasoningHandler(),
         AnswerHandler(),

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/agent/conversation/transcript/stream.py

@@ -164,7 +164,11 @@ class StreamMixin(TurnMixin):
             return
         # An unknown status is refused before the row is touched at all.
         outcome = EntryStatus(status)
-        entry.text = limit_output(self.renderers.body(entry.tool, output))
+        body = self.renderers.body(entry.tool, output)
+        entry.text = limit_output(body)
+        # The result, unbounded: a count is of what came back, not of the preview the row keeps, and what it says about
+        # the body depends on whether the call worked.
+        self.renderers.finished(entry, body, outcome)
         entry.finish(outcome, self.clock())
         self._changed(entry)
         # The loop calls the model again once the batch has produced its

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/commands.py

@@ -101,19 +101,24 @@ class CommandHost(Protocol):
     async def run_side_question(self, question: str) -> None:
         """Answer a question that is kept out of the conversation."""
 
-    async def prompt(self, text: str) -> bool:
+    async def prompt(self, text: str, *, shown: str | None = None) -> bool:
         """Run ``text`` as one turn of this conversation, exactly as if the reader had typed it.
 
-        The text reaches the model the way a draft does: echoed in the transcript as the reader's own message,
-        stored in the session, streamed as it is answered, and settled by the same row. ``@`` references are
-        resolved; pictures the text cannot carry are not part of it.
+        The text reaches the model the way a draft does: stored in the session, streamed as it is answered, and
+        settled by the same row. ``@`` references are resolved.
+
+        A command whose instructions are longer than what it wants to show passes the two apart: ``text`` is what
+        the model reads, ``shown`` is what the transcript draws in its place. A reader who typed ``/code-review``
+        sees that, not the brief it stands for — while the model reads the brief with that turn, then and in every
+        later turn, because the brief is part of the message the session keeps. Only its display is short.
 
         The turn is awaited, so the command that asked for it holds the request slot until it has been answered,
         and the row the shell shows is the command's own.
 
         Args:
-            text: What to ask. Its own text is what the reader sees, so a command that builds the text should
-                write it as a reader would have.
+            text: What to ask. With no ``shown``, this is also what the reader sees.
+            shown: What the transcript shows, when it differs from ``text``. The message the session keeps is
+                the same either way: ``text`` is in it, and ``shown`` is what a reader is shown of it.
 
         Returns:
             Whether a turn was started and has ended. A request already running, a blank text and a session held

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/plugins/builtin_commands.py

@@ -18,6 +18,10 @@ walked (``/theme``, ``/pet``) and the panels that edit a form of their own (``/c
 from __future__ import annotations
 
 import asyncio
+import os
+import shlex
+import subprocess
+import sys
 from pathlib import Path
 
 from zettcode.app.commands import (
@@ -447,6 +451,126 @@ class BashCommand(TerminalPlugin):
         return CommandResult(widget=page)
 
 
+class CodeReview(TerminalPlugin):
+    """``/code-review``: ask for a review of the uncommitted changes, in this conversation."""
+
+    name = "code-review-command"
+    description = "code review"
+
+    #: What the model is asked, in pieces: a preset for the turn, not a report about it. The reader gets the review
+    #: as an answer they could have asked for by typing all of this themselves.
+    INTRO = "Review the uncommitted changes in this workspace."
+    COLLECT = (
+        "Collect them first: `git status --short` for what changed, `git diff HEAD` for the patch, and the contents "
+        "of any untracked file that belongs to the change."
+    )
+    #: The reviewer is a session of its own, at the shell level of the reader who asked — never above it, since
+    #: nobody here approved anything. `{spawn}` is the whole line to run, so the model copies it rather than
+    #: reassembling an alias.
+    DAEMON = (
+        "Have it read by a reviewer of its own, so this conversation keeps its context. `{command} list` shows the "
+        "daemons running on this machine. If one is already there for this workspace — `code-review` is the name "
+        "this command gives one — reuse it rather than starting another: it has read the earlier rounds and "
+        "already knows this change, which makes it the better reviewer. Send it what you need with "
+        '`send_message(to="<session id>", message=...)` — the request as you would put it, and that the change '
+        "is the uncommitted diff this workspace holds, which it can collect itself. Only when there is none, run\n"
+        "\n"
+        "    {spawn}\n"
+        "\n"
+        "and take the session id it prints; it is recorded under the name `code-review`, so the next review in "
+        "this workspace finds it.\n"
+        "\n"
+        "Say in that message, every round, that it must answer: send its findings back to you with `send_message`, "
+        "and if it has nothing to change, say that in a word. A reviewer that goes quiet leaves the change "
+        "waiting, and a review that found nothing cannot be told apart from one that never happened.\n"
+        "\n"
+        "Keep the reviewer running while you work on what it found: make the changes here, then send it the new "
+        "state of the change for another look, and go round again until it has nothing left to say. A reviewer "
+        "stopped after the first round cannot tell you whether the fix worked. If a round brings no answer at all, "
+        "send the request once more; if that also goes unanswered, read what it did say: its conversation is "
+        "`~/.zettcode/sessions/*/<session id>/data.jsonl`, and the last assistant message in it is its review — "
+        "report that here, then stop it with `{command} kill <session id>` so that it is not left running. If a "
+        "daemon cannot be started here, say why and do the review yourself."
+    )
+    #: A reviewer is told plainly what it is: the instruction is the safeguard, and the reader is told the same in
+    #: the guide, since a session at `full` could change things if it chose to.
+    NOT_YOURS = (
+        "Tell the reviewer plainly that it reads and does not change: no edits, no writes, no commits, no command "
+        "that modifies the workspace. The changes are yours to make, and you keep making them, round after round, "
+        "until nothing it found is left."
+    )
+    #: Under `deny` there is no shell for a daemon to collect a diff with, and the session that asked has none
+    #: either: the review is a reading one.
+    ALONE = (
+        "This session runs no shell commands, so neither the diff nor a daemon to read it can be gathered: review "
+        "the files themselves with the reading tools, and say which ones you read."
+    )
+    SHAPE = (
+        "In the review, name concrete problems with `file:line` — correctness, error handling, tests, naming — say "
+        "what you would change and why, and do not restate the diff.\n"
+        "\n"
+        "What to pay attention to: {focus}"
+    )
+
+    #: The shell levels a reviewer may be started at. `ask` has no meaning in a process nobody sits at, so it is
+    #: started `safe`: sandboxed, which is still more than a reader at `ask` has granted.
+    LEVELS = {"full": "full", "safe": "safe", "ask": "safe"}
+
+    def activate(self, container: TerminalContainer) -> None:
+        """Register the command; it queues, since a review is a request like any other."""
+        container.register_command(
+            "code-review",
+            "review the uncommitted changes: /code-review [what to look for]",
+            self.review,
+            when_busy="queue",
+        )
+
+    async def review(self, context: CommandContext) -> CommandResult:
+        """Run the review as one turn, with what the reader typed as its focus.
+
+        The command adds no work of its own: it writes the brief, hands it to `host.prompt`, and the ordinary turn
+        does the rest — the echo in the transcript, the session, the streaming, the line it ends on. Nothing is
+        gathered here, so the model decides what the review needs and how to get it.
+
+        The transcript shows the command the reader typed, not the brief it stands for: the brief is what the model
+        reads, and `shown` is what the conversation keeps.
+        """
+        host = context.require_host()
+        argument = context.argument.strip()
+        focus = argument or "anything that would make this change wrong or hard to keep"
+        shown = f"/code-review {argument}" if argument else "/code-review"
+        await host.prompt(self.brief(level=host.client.permission, focus=focus), shown=shown)
+        return CommandResult()
+
+    def brief(self, *, level: str, focus: str) -> str:
+        """Return what the model reads, for a reader whose shell level is ``level``.
+
+        The reviewer is started at the reader's own level (`ask` becoming `safe`, which is what a level that asks
+        means in a process nobody can answer in), and not at all under `deny`.
+        """
+        command = self.command()
+        parts = [self.INTRO, self.COLLECT]
+        if level in self.LEVELS:
+            spawn = f"{command} spawn --name code-review --permission {self.LEVELS[level]}"
+            parts.append(self.DAEMON.format(command=command, spawn=spawn))
+            parts.append(self.NOT_YOURS)
+        else:
+            parts.append(self.ALONE)
+        parts.append(self.SHAPE.format(focus=focus))
+        return "\n\n".join(parts)
+
+    @staticmethod
+    def command() -> str:
+        """Return the command that runs this installation's daemon, quoted for the shell that will run it.
+
+        `python -m zettcode.daemon` and the interpreter that is running this terminal: a checkout whose console
+        script is not on the PATH, or a virtualenv nothing else can see, still works. The quoting follows the
+        platform's shell, because a Windows path with a space cannot be passed the way POSIX quotes it.
+        """
+        argv = [sys.executable, "-m", "zettcode.daemon"]
+        return subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+
+
 class ShellControl(TerminalPlugin):
     """``/clear``, ``/quit`` and ``/exit``."""
 

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/plugins/builtins.py

@@ -27,7 +27,15 @@ from zettcode.app.ui.widgets import UsagePage
 from zettcode.statusline import TURN_PARTS, Row, context_share, usage_parts
 from zettcode.tui import STATUS, bundled_themes
 
-from .builtin_commands import BashCommand, HelpCommand, ModelCommands, SessionCommands, ShellControl, SideQuestion
+from .builtin_commands import (
+    BashCommand,
+    CodeReview,
+    HelpCommand,
+    ModelCommands,
+    SessionCommands,
+    ShellControl,
+    SideQuestion,
+)
 from .container import TerminalContainer
 from .plugin import TerminalPlugin
 from .state import ShellContext, TurnBuilder
@@ -171,6 +179,7 @@ BUILTIN_PLUGINS: tuple[TerminalPlugin, ...] = (
     SessionCommands(),
     ModelCommands(),
     SideQuestion(),
+    CodeReview(),
     BashCommand(),
     ShellControl(),
     TurnLine(),

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/ui/app.py

@@ -49,7 +49,7 @@ if TYPE_CHECKING:  # pragma: no cover - annotations only
     pass
 from zettcode.error_text import describe_error
 from zettcode.mentions import MentionRegistry, SessionMentions
-from zettcode.prompt import PromptPart, carries_image, mention_hint, mention_parts
+from zettcode.prompt import PromptPart, carries_image, mention_parts
 from zettcode.registry import Registry
 from zettcode.relay import Relayed
 from zettcode.sdk.events import QuestionAsked
@@ -238,6 +238,7 @@ class ZettCodeApp(
         #: that never started one — because the update check is off, or because it
         #: is leaving before the background work began — has nothing else to drop.
         self._update_task: asyncio.Task[None] | None = None
+        self._updating = False
         self._theme_before = None
         self._previewing = None
         #: The runtime warm-up this shell started, released on the way out.
@@ -659,7 +660,7 @@ class ZettCodeApp(
             if outcome:
                 self._settle_wait(outcome)
 
-    async def prompt(self, text: str) -> bool:
+    async def prompt(self, text: str, *, shown: str | None = None) -> bool:
         """Run ``text`` as one turn of this conversation, as if the reader had typed it.
 
         The draft path is taken whole — the echo, ``@`` references, the transcript, the session, the row the
@@ -667,16 +668,31 @@ class ZettCodeApp(
         a reader could have produced. What the command decides is the text; everything after that is the ordinary
         one.
 
+        With ``shown``, the reader sees one thing and the model reads another: the shown text is what the turn
+        draws in the transcript, and the text is the instructions the model reads after it. Both are in the message
+        the session keeps — the instructions are not dropped, they are only kept out of what is displayed — so a
+        later turn, and a restored session, still have them in front of the model.
+
         The turn is awaited, so the request slot stays the command's until the answer is in: a second draft cannot
         start behind it, and the command reports what it did once it is done.
         """
         if not text.strip():
             return False
+        if self._updating:
+            self.flash("updating ZettCode \u2014 this window takes no input until it is done", level="info")
+            return False
         if self.client.session.locked:
             self.flash("this session is open in another ZettCode process; it is read-only here", level="error")
             return False
-        parts = mention_parts((text,), self.mentions)
-        await self._run_prompt(text, parts, mention_hint(parts, self.mentions), advance=False)
+        display = (shown if shown is not None else text).strip() or text.strip()
+        if display == text.strip():
+            # No `@` pass here: the SDK resolves the references itself (it is asked for them below), and doing
+            # both is how the same instructions once reached the model twice.
+            await self._run_prompt(text, (), advance=False)
+        else:
+            # The brief is not the reader's message: it rides after the shown text, which is what the transcript
+            # draws. The SDK keeps both in the message and shows the reader the first.
+            await self._run_prompt(display, (), instructions=text, advance=False)
         return True
 
     async def run_continue(self) -> None:
@@ -835,6 +851,11 @@ class ZettCodeApp(
         """
         if command is None:
             command = self._is_command(value)
+        if self._updating:
+            # The installation is being replaced under this process: nothing typed now can be run against it, and a
+            # half-installed package is not a thing to hand a prompt to.
+            self.flash("updating ZettCode \u2014 this window takes no input until it is done", level="info")
+            return False
         if self.client.session.locked and not command:
             # Only commands are taken, which is how a reader leaves: the composer does not let anything else be
             # typed, and this is for what arrives some other way (a draft that was there already, a recall).
@@ -873,7 +894,7 @@ class ZettCodeApp(
                 self.transcript.error(f"{self.client.model.name} does not take images")
                 self.app.invalidate()
                 return False
-            self._task = asyncio.create_task(self._run_prompt(value, parts, mention_hint(parts, self.mentions)))
+            self._task = asyncio.create_task(self._run_prompt(value, parts, instructions=None))
         return True
 
     def _queue_steering(self, value: str, key: str | None = None, parts: Sequence[PromptPart] = ()) -> None:
@@ -981,8 +1002,8 @@ class ZettCodeApp(
         self,
         prompt: str,
         parts: Sequence[PromptPart] = (),
-        hint: str | None = None,
         *,
+        instructions: str | None = None,
         relayed: Relayed | None = None,
         advance: bool = True,
     ) -> None:
@@ -993,8 +1014,9 @@ class ZettCodeApp(
                 into the transcript.
             parts: The same turn as ordered text and image parts; an empty
                 sequence falls back to the prompt alone.
-            hint: Instructions the draft's ``@`` references contribute; the
-                stored message keeps ``prompt``.
+            instructions: What the model reads after the prompt but the reader does not: the SDK resolves the
+                draft's ``@`` references itself, so this carries only what a command adds (see
+                :meth:`CommandHost.prompt`). The stored message keeps ``prompt``.
             relayed: The turn answers a message another session sent, which the transcript draws as
                 that, the model is told where it came from, and the session stores as that.
         """
@@ -1029,7 +1051,12 @@ class ZettCodeApp(
                     **self._answers(),
                 )
             else:
-                run = self.client.session.prompt(prompt_pieces(parts or (prompt,)), mentions=True, **self._answers())
+                run = self.client.session.prompt(
+                    prompt_pieces(parts or (prompt,)),
+                    mentions=True,
+                    instructions=instructions,
+                    **self._answers(),
+                )
             async with run:
                 async for event in run:
                     tally.see(event)

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/ui/followups.py

@@ -18,7 +18,7 @@ import asyncio
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from zettcode.prompt import PromptPart, carries_image, mention_hint, mention_parts
+from zettcode.prompt import PromptPart, carries_image, mention_parts
 from zettcode.tui import Screen
 from zettcode.tui.render import truncate
 
@@ -423,4 +423,4 @@ class FollowUpsMixin(ShellState):
         # be able to start a second turn beside it.
         self._set_busy(True)
         parts = mention_parts(item.parts, self.mentions)
-        self._task = asyncio.create_task(self._run_prompt(item.text, parts, mention_hint(parts, self.mentions)))
+        self._task = asyncio.create_task(self._run_prompt(item.text, parts))

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/ui/keys.py

@@ -59,7 +59,12 @@ class KeysMixin(ShellState):
             "ctrl_d",
             "quit",
             priority="capture",
-            when=lambda: self.app.screens.top.name != PAGE_SCREEN and not self._busy and not self.composer.text,
+            when=lambda: (
+                self.app.screens.top.name != PAGE_SCREEN
+                and not self._busy
+                and not self.composer.text
+                and not self._updating
+            ),
         )
         # The follow-up list. The modifier key (Option on a Mac) is the list's own: with
         # nothing highlighted it walks into the list from the composer's side, and with a

{zettcode-0.1.12 → zettcode-0.2.0}/src/zettcode/app/ui/messaging.py

@@ -134,6 +134,8 @@ class MessagingMixin(ShellState):
         """
         if not self._messaging_live:
             return Receipt(False, "this session is closing")
+        if self._updating:
+            return Receipt(False, "this window is installing an update; try again when it is done")
         if self.client.session.locked:
             return Receipt(False, "this session is open in another ZettCode process, so it is read-only here")
         if not self._busy:
@@ -156,11 +158,11 @@ class MessagingMixin(ShellState):
         # Busy before the task has run, exactly as for a follow-up: between here and its first step a
         # second message, or a keystroke, must not be able to start a turn beside this one.
         self._set_busy(True)
-        self._task = asyncio.create_task(self._run_prompt(relayed.text, (relayed.text,), None, relayed=relayed))
+        self._task = asyncio.create_task(self._run_prompt(relayed.text, (relayed.text,), relayed=relayed))
 
     def _start_next_relayed(self) -> bool:
         """Start the oldest waiting message, if there is one and nothing is running."""
-        if self._busy or not self._inbox:
+        if self._busy or self._updating or not self._inbox:
             return False
         self._start_relayed(self._inbox.pop(0))
         return True