zettcode 0.1.11__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.11
+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.11 → 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.11 → 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.11"
+__version__ = "0.2.0"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

{zettcode-0.1.11 → 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.11 → 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.11 → 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.11 → zettcode-0.2.0}/src/zettcode/app/agent/conversation/tips.py

@@ -22,7 +22,7 @@ TIPS: tuple[str, ...] = (
     "Type while it works: your message can steer this request, or wait and follow it.",
     "Press Shift-Enter (or Alt-Enter) to add a line to your message instead of sending it.",
     "Type @ to mention a file or a skill. A file is read when the message is sent.",
-    "Start a message with @name to send it to another running ZettCode session.",
+    "Type @ to mention another running ZettCode session; the model can pass your message to it.",
     "/btw <question> is answered on the side and never joins the conversation.",
     "/bash opens a full-screen command line: your shell's history, Tab completion, and coloured output.",
     "In /bash, Tab completes git subcommands and branches, and Ctrl-C stops a running command.",

{zettcode-0.1.11 → 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.11 → zettcode-0.2.0}/src/zettcode/app/commands.py

@@ -101,6 +101,31 @@ 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, *, 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: 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. 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
+            by another process answer ``False``, and nothing is started. A command that means to be usable
+            mid-request says ``when_busy="queue"``, and this then runs when the request in flight has ended.
+        """
+
     def change_model(self, name: ModelInfo | str) -> ModelInfo:
         """Switch models and announce the change in the transcript."""
 

{zettcode-0.1.11 → 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.11 → 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.11 → 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
@@ -135,8 +135,8 @@ class ZettCodeApp(
         # The plugins' commands reach the shell through the context they are run with, and the words their menus
         # offer through this link; the shell is built enough by now that either may follow it.
         agent.attach_host(self)
-        #: The line to the other sessions, when the configuration has one; the session names it offers
-        #: for ``@`` come first, because a draft that begins with one is a message to that session.
+        #: The line to the other sessions, when the configuration has one; a session name it offers for ``@``
+        #: comes first, so it wins over a file or plugin resource of the same name.
         self.messenger: SessionLink | None = agent.messenger
         self.mentions = MentionRegistry(
             agent.plugin_mentions
@@ -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.
@@ -254,7 +255,6 @@ class ZettCodeApp(
         self._follow_ups_held = False
         self._turn_running = False
         self._inbox: list[Relayed] = []
-        self._sends: set[asyncio.Task[None]] = set()
         self._lock_watch: asyncio.Task[None] | None = None
         self._lock_said: str | None = None
         self._messaging_live = False
@@ -660,6 +660,41 @@ class ZettCodeApp(
             if outcome:
                 self._settle_wait(outcome)
 
+    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
+        request ends on — rather than a run of its own, so a command that asks the model something produces a turn
+        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
+        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:
         """Pick up the request that was interrupted, where it stopped, as a turn of the conversation.
 
@@ -816,17 +851,16 @@ 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).
             self.flash("this session is open in another ZettCode process; it is read-only here", level="error")
             return False
-        if not command:
-            # A draft that begins with the name of an active session is a message to it: sent whatever this
-            # session is doing, because it is not a request to this session's model.
-            sent = self._send_session_message(self.composer.parts())
-            if sent is not None:
-                return sent
         if self._busy:
             if command:
                 # Which commands are taken mid-request is the command's own
@@ -860,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:
@@ -968,9 +1002,10 @@ class ZettCodeApp(
         self,
         prompt: str,
         parts: Sequence[PromptPart] = (),
-        hint: str | None = None,
         *,
+        instructions: str | None = None,
         relayed: Relayed | None = None,
+        advance: bool = True,
     ) -> None:
         """Stream one agent turn, keeping the task panel and transcript current.
 
@@ -979,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.
         """
@@ -1015,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)
@@ -1056,7 +1097,10 @@ class ZettCodeApp(
             self._note = None
             self._refresh_tasks()
             self.app.invalidate()
-            self._start_next_command()
+            if advance:
+                # A turn a command asked for leaves this to the command: it is still running, and what was queued
+                # waits for it to end, not for the turn inside it.
+                self._start_next_command()
 
     def _set_busy(self, busy: bool) -> None:
         """Track in-flight work and keep the frame loop alive while it runs.

{zettcode-0.1.11 → 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.11 → 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