zettcode 0.3.1__tar.gz → 0.3.2__tar.gz

{zettcode-0.3.1 → zettcode-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.3.1
+Version: 0.3.2
 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,9 +35,14 @@ 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.2
+Requires-Dist: zett-agent<0.3,>=0.2.4
+Provides-Extra: all
+Requires-Dist: zettcode-monitor<0.3,>=0.2; extra == 'all'
+Requires-Dist: zettcode-recap<0.2,>=0.1; extra == 'all'
 Provides-Extra: monitor
 Requires-Dist: zettcode-monitor<0.3,>=0.2; extra == 'monitor'
+Provides-Extra: recap
+Requires-Dist: zettcode-recap<0.2,>=0.1; extra == 'recap'
 Description-Content-Type: text/markdown
 
 # ZettCode

{zettcode-0.3.1 → zettcode-0.3.2}/pyproject.toml

@@ -61,7 +61,7 @@ dependencies = [
   # now leans on: a hosted tool the provider left open is closed with
   # ``output={"status": "not_reported"}`` instead of leaving the step waiting, and
   # `engine/server_tools.describe_output` reads that to say so.
-  "zett-agent>=0.2.2,<0.3",
+  "zett-agent>=0.2.4,<0.3",
 ]
 
 [project.optional-dependencies]
@@ -72,11 +72,15 @@ dependencies = [
 # that accepts it (its range has to allow both lines in between), or `pip install zettcode==<new>` would fail to
 # resolve, and so would the environment the VS Code extension builds for itself.
 monitor = ["zettcode-monitor>=0.2,<0.3"]
+# `/recap` for a reader who steps away. Published on its own line like the one above, and an extra for the same
+# reason: a hard edge would tie the two releases together.
+recap = ["zettcode-recap>=0.1,<0.2"]
+# Every plugin this repository publishes, for a reader who wants the lot: `pip install "zettcode[all]"`.
+all = ["zettcode-monitor>=0.2,<0.3", "zettcode-recap>=0.1,<0.2"]
 
 [project.scripts]
 zettcode = "zettcode.cli:main"
 zettcode-server = "zettcode.server.cli:main"
-zettcode-gateway = "zettcode.gateway.cli:main"
 
 [project.urls]
 Repository = "https://github.com/Chang-LeHung/zettcode"

{zettcode-0.3.1 → zettcode-0.3.2}/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.3.1"
+__version__ = "0.3.2"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/agent/commands.py

@@ -7,6 +7,9 @@ agent is where the shell asks for everything the runtime loaded.
 
 from __future__ import annotations
 
+import asyncio
+from collections.abc import Callable
+
 from zettcode.app.commands import Command, CommandContext, CommandHost, CommandResult
 from zettcode.app.pets import PetCatalog, bundled_pets
 from zettcode.app.plugins.host import HOST_LINK, HostLink
@@ -116,6 +119,21 @@ class CommandsMixin(AppearanceMixin, ExportsMixin):
         """Return the header and status rows plugins asked the shell to draw."""
         return self.terminal_plugins.rows
 
+    @property
+    def plugin_focus_handlers(self) -> tuple[Callable[[bool], None], ...]:
+        """Return the handlers told when the terminal window gains or loses focus."""
+        return self.terminal_plugins.focus_handlers
+
+    @property
+    def plugin_turn_start_handlers(self) -> tuple[Callable[[], None], ...]:
+        """Return the handlers told when a turn of the conversation starts."""
+        return self.terminal_plugins.turn_start_handlers
+
+    @property
+    def plugin_turn_end_handlers(self) -> tuple[Callable[[bool], None], ...]:
+        """Return the handlers told when a turn of the conversation ends."""
+        return self.terminal_plugins.turn_end_handlers
+
     async def _command_new(self, context: CommandContext) -> CommandResult:
         """Start a fresh session."""
         session_id = self.new_session()
@@ -218,10 +236,28 @@ class CommandsMixin(AppearanceMixin, ExportsMixin):
     async def _command_compact(self, context: CommandContext) -> CommandResult:
         """Summarize the conversation now, whatever its size.
 
-        The row and the outcome notice arrive while this await runs: the pass
-        dispatches through the same event dispatcher a turn does, so the
-        transcript animates ``Compacting`` and ends with ``Context compaction
-        applied`` (or ``skipped`` when the summary would not be smaller).
+        The row is opened only after the refusal check. That check may read a
+        cold session on a worker, so the interface stays live while it runs;
+        once the row is up, the shell draws it before the pass starts. What
+        follows the first ``await`` is still synchronous token counting and the
+        summary request, so a row created only by ``CompactionStarted`` would
+        reach the screen after the work it was meant to explain.
         """
-        await self.compact()
+        host = context.host
+        if host is not None:
+            await self.ensure_compactable()
+            host.transcript.start_compaction()
+        try:
+            if host is not None:
+                await host.wait_for_frame()
+                await self._compact_pass()
+            else:
+                await self.compact()
+        except asyncio.CancelledError:
+            if host is not None:
+                host.transcript.complete_compaction("Compacting stopped")
+            raise
+        finally:
+            if host is not None:
+                host.transcript.complete_compaction()
         return CommandResult()

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/entries.py

@@ -321,6 +321,8 @@ class MessageEntry(ToolEntry):
 
     to: str = ""
     message: str = ""
+    #: The group chat it was written to (without the ``#``), or empty for one session: the row says which.
+    group: str = ""
 
     @property
     def foldable(self) -> bool:
@@ -378,3 +380,5 @@ class RelayEntry(Entry):
     by_agent: bool = True
     external: bool = False
     note: str = ""
+    #: The group chat it was written in (without the ``#``); empty for a one-to-one message.
+    group: str = ""

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/presenters.py

@@ -440,6 +440,10 @@ class RelayPresenter(Presenter[RelayEntry]):
                 else f"\u2190 {'agent' if entry.by_agent else 'user'} of session {peer}"
             )
             detail = ""
+            if entry.group:
+                # A group message is read by every member: say so in the header, where a one-to-one message has nothing.
+                label += f" in #{terminal_safe(entry.group)}"
+                detail = f" {SEPARATOR} to the whole group"
 
         def row(*spans: Span) -> TextLine:
             used = sum(display_width(span.text) for span in spans)

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/projection.py

@@ -7,6 +7,7 @@ terminal shows and what the SDK reports cannot drift apart.
 
 from __future__ import annotations
 
+import logging
 from collections.abc import Callable
 
 from zett_agent.dispatcher import AgentEventDispatcher
@@ -55,6 +56,9 @@ class _NobodyAnswers:
         raise RuntimeError("This projector has no agent to carry an answer to")
 
 
+logger = logging.getLogger("zettcode.terminal")
+
+
 class TranscriptProjector(AgentEventDispatcher):
     """Turn AgentClient callbacks into transcript blocks.
 
@@ -71,8 +75,9 @@ class TranscriptProjector(AgentEventDispatcher):
         on_approval: Callable[[ApprovalRequested], None] | None = None,
         on_ask: Callable[[QuestionAsked], None] | None = None,
         on_usage: Callable[[Usage, str], None] | None = None,
-        on_steering_started: Callable[[str], None] | None = None,
+        on_steering_started: Callable[[str], Relayed | str | None] | None = None,
         on_steering_interrupted: Callable[[str], None] | None = None,
+        side_running: Callable[[], bool] | None = None,
     ) -> None:
         """Send projected events to ``transcript``; approvals go to ``on_approval``.
 
@@ -89,9 +94,18 @@ class TranscriptProjector(AgentEventDispatcher):
                 the shell can refresh the status line without polling the store.
             on_steering_started: Called with the text of a queued steering
                 message the agent just adopted, so the shell can drop it from
-                the pending queue before the row is echoed.
+                the pending queue before the row is echoed. What it returns, when
+                it is a :class:`~zettcode.relay.Relayed`, is drawn as that session's
+                message — what its sender wrote, not the line the model reads; a
+                string is drawn as the row's text.
             on_steering_interrupted: Called with the text of a steering message
                 a newer one superseded, so the shell can drop it too.
+            side_running: Asked whether the run in flight is a side question — a question the model answers without
+                the exchange joining the conversation. Such a run is drawn only when the shell began it, so a
+                plugin that asks one for itself (a recap) is not also drawn as an answer of its own. ``None``
+                treats every run as one the shell began. Two plain flags are enough here because the SDK runs one
+                request at a time: a second run is refused while one is in flight, so a plugin's ask cannot
+                overlap a turn the shell began and a stale answer cannot be drawn as a turn's.
         """
         self.transcript = transcript
         self.bridge: Bridge = bridge if bridge is not None else _NobodyAnswers()
@@ -103,27 +117,58 @@ class TranscriptProjector(AgentEventDispatcher):
         #: What a hosted tool's input has streamed so far, by call. The translation fills it as fragments arrive
         #: and reads the query out of it when the call reports back.
         self._hosted: dict[str, str] = {}
+        #: Whether the shell began the run in flight, and so draws it.
+        self._begun = False
+        #: Whether a run nobody began has been reported as left out, so dropping one is a line and not one per
+        #: token; it is cleared when a turn is begun, so it reports the next run that way too.
+        self._reported_side = False
+        self._side_running = side_running
 
     def begin_turn(self, prompt: str, *, side: bool = False, relayed: Relayed | None = None) -> None:
-        """Echo the prompt into the transcript before the run starts.
+        """Begin drawing one run into the transcript, echoing the prompt that asked for it.
+
+        The shell begins a turn before every run it shows on screen, which is also how a side question it asked
+        is told apart from one a plugin asked for itself: see ``side_running``.
 
         Args:
-            prompt: What the reader asked.
+            prompt: What the reader asked, echoed as the turn's first row.
             side: The question is a side one, which the transcript shows as such.
             relayed: The turn answers a message another session sent, which the transcript shows as that.
         """
+        # The row first, the flag second: an echo that raises leaves no run to draw, and a flag set before it would
+        # stay set, drawing every later side question as an answer of its own.
         if relayed is None:
             self.transcript.begin_turn(prompt, side=side)
         else:
             self.transcript.begin_turn(prompt, side=side, relayed=relayed)
+        self._begun = True
+        self._reported_side = False
+
+    def end_turn(self) -> None:
+        """Stop drawing, once the run the shell began has ended.
+
+        Nothing of whatever runs next is drawn until a turn is begun for it, which is what keeps a plugin's own
+        side question out of the transcript between turns.
+        """
+        self._begun = False
 
     async def dispatch(self, event: AgentEvent) -> None:
         """Note that the agent spoke, then draw what the event stands for.
 
         Every event ends a silence, whichever it is: the waiting row counts how long it has been since the model
         last said anything, and has to be told each time it does.
+
+        A side question the shell did not begin is left out: its answer would land under the last turn's line as a
+        reply nobody asked for, and whoever asked for it — a plugin's recap — draws the part it wants itself. The
+        drop is logged, a line rather than one per token, so an answer that is missing from the transcript can be
+        explained from the log.
         """
         self.transcript.heard()
+        if not self._begun and self._side_running is not None and self._side_running():
+            if not self._reported_side:
+                self._reported_side = True
+                logger.debug("projector.side_not_drawn", extra={"session": event.session_id})
+            return
         for translated in translate(event, self.bridge, self._hosted):
             self.project(translated, event)
 
@@ -147,8 +192,10 @@ class TranscriptProjector(AgentEventDispatcher):
             case ReasoningFinished():
                 transcript.complete_thinking()
             case ToolStarted(call_id=call_id, name=name, arguments=arguments):
+                logger.debug("tool.start", extra={"tool": name, "call": call_id})
                 transcript.start_tool(call_id, name, arguments)
             case ToolFinished(call_id=call_id, name=name, output=output, ok=ok, skipped=skipped):
+                logger.debug("tool.finish", extra={"tool": name, "call": call_id, "ok": ok, "skipped": skipped})
                 self._tool_finished(call_id, name, output, ok, skipped)
             case ServerToolStarted(call_id=call_id, name=name, arguments=arguments):
                 transcript.start_tool(call_id, name, arguments)
@@ -174,9 +221,11 @@ class TranscriptProjector(AgentEventDispatcher):
                 if stop is not None and not stop.ok:
                     transcript.error(stop_text(stop))
             case Steered(text=text):
-                if self.on_steering_started is not None:
-                    self.on_steering_started(text)
-                transcript.begin_turn(text)
+                adopted = self.on_steering_started(text) if self.on_steering_started is not None else None
+                if isinstance(adopted, Relayed):
+                    transcript.begin_turn(adopted.text, relayed=adopted)
+                else:
+                    transcript.begin_turn(adopted or text)
             case SteeringFinished():
                 transcript.complete_thinking()
             case SteeringInterrupted(text=text):

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/rendering.py

@@ -667,7 +667,10 @@ class MessageTool(ToolHandler):
     names = frozenset({"send_message"})
 
     def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
-        """Say who it is for; an id is shortened to its end, which is how a session is named without a title."""
+        """Say who it is for: a group as ``#name`` (everyone in it reads it), a session by name or the end of its id."""
+        group = argument(arguments, "group")
+        if group:
+            return ToolRow(f"Message to group #{group.lstrip('#')}")
         return ToolRow(f"Message to {self._recipient(argument(arguments, 'to', '(unknown)'))}")
 
     @staticmethod
@@ -686,11 +689,43 @@ class MessageTool(ToolHandler):
             tool=name,
             title=self.describe(name, arguments).title,
             to=argument(arguments, "to"),
+            group=argument(arguments, "group").lstrip("#"),
             message=limit_output(message) if isinstance(message, str) else "",
             started_at=started_at,
         )
 
 
+class HistoryTool(ToolHandler):
+    """``message_history``: what was said before, with one session or in a group."""
+
+    names = frozenset({"message_history"})
+
+    def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
+        """Say whose history it reads: a group's as ``#name``, one session's by name or the end of its id."""
+        group = argument(arguments, "group")
+        if group:
+            return ToolRow(f"Read history of group #{group.lstrip('#')}")
+        session = argument(arguments, "session")
+        if session:
+            return ToolRow(f"Read history with {MessageTool._recipient(session)}")
+        return ToolRow("Read message history")
+
+
+class GroupTool(ToolHandler):
+    """``manage_group``: make or change a group chat."""
+
+    names = frozenset({"manage_group"})
+
+    _VERBS = {"create": "Create", "add": "Add to", "remove": "Remove from", "leave": "Leave", "delete": "Delete"}
+
+    def describe(self, name: str, arguments: Mapping[str, object]) -> ToolRow:
+        """Say what is done to which group, and with whom."""
+        verb = self._VERBS.get(argument(arguments, "action"), "Change")
+        members = argument(arguments, "members")
+        with_ = f" with {members}" if members and verb in ("Create", "Add to", "Remove from") else ""
+        return ToolRow(f"{verb} group #{argument(arguments, 'group').lstrip('#') or '(unknown)'}{with_}")
+
+
 class NamespacedTool(ToolHandler):
     """A tool whose name carries where it came from: ``server__tool``, so the row names the server.
 
@@ -785,6 +820,8 @@ DEFAULT_RENDERERS = Renderers(
         SkillTool(),
         TaskTool(),
         MessageTool(),
+        HistoryTool(),
+        GroupTool(),
         NamespacedTool(),
         FallbackTool(),
         ReasoningHandler(),

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/text.py

@@ -245,11 +245,14 @@ def calls_text(usage: Usage) -> str | None:
 
 
 def speed_text(usage: Usage) -> str | None:
-    """Say how fast the model generated, when it can be told and is at least one token a second."""
-    if usage.requests and usage.seconds > 0 and usage.output_tokens > 0:
-        rate = usage.output_tokens / usage.seconds
-        if rate >= 1:
-            return f"{rate:.1f} tok/s" if rate < 10 else f"{rate:.0f} tok/s"
+    """Say how fast the model generated, when it can be told and is at least one token a second.
+
+    Reads :attr:`Usage.output_rate`, which leaves the opening chunk's tokens out of the numerator, so this line and the
+    status line a reader sees above it never disagree.
+    """
+    rate = usage.output_rate
+    if usage.requests and rate is not None and rate >= 1:
+        return f"{rate:.1f} tok/s" if rate < 10 else f"{rate:.0f} tok/s"
     return None
 
 

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/tips.py

@@ -44,7 +44,7 @@ TIPS: tuple[str, ...] = (
     "/usage shows tokens, cache and cost by day, model and session; /resume lists them per session.",
     "/statusline chooses what the header and the status line show, and turns the pet on.",
     "/pet picks a companion that sleeps while idle and works while a request runs; drag it anywhere.",
-    "/self-compact lets the model decide for itself when to compact this session.",
+    "/plugins can turn self-compaction on or off: the model decides when to compact its own context.",
     "zettcode resume <id> opens a stored session; zettcode update installs the newest release.",
     "zettcode doctor checks every configured model from a shell, with no session started.",
     "zettcode --full skips every shell question and the sandbox for that run; /permission can change it later.",

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/transcript/oneoff.py

@@ -31,8 +31,8 @@ class OneOffMixin(EntryLog):
         self._add(TextEntry(id=self._next_id, kind=EntryKind.ANNOUNCEMENT, text=text))
 
     def model_changed(self, previous: str, current: str) -> None:
-        """Announce a model change in the conversation."""
-        self.announce(f"Model changed from {previous} to {current}.")
+        """Announce a model change in the conversation; an empty previous is the first model there has been."""
+        self.announce(f"Model changed from {previous} to {current}." if previous else f"Model set to {current}.")
 
     def permission_changed(self, previous: str, current: str) -> None:
         """Announce a shell-permission change the way a model change is shown."""

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/transcript/stream.py

@@ -87,11 +87,20 @@ class StreamMixin(TurnMixin):
         row.text += delta
         self._changed(row)
 
-    def complete_compaction(self) -> None:
-        """Close the running compaction row and stamp its elapsed time."""
+    def complete_compaction(self, text: str = "") -> None:
+        """Close the running compaction row and stamp its elapsed time.
+
+        Args:
+            text: What to leave in place of the streamed summary, when the pass
+                ended before writing one — a stop, for example. The row is
+                expanded so the note is on its face rather than in a fold.
+        """
         row = self._last(ThinkingEntry)
         if row is None or row.title != COMPACTING_LABEL or not row.running:
             return
+        if text:
+            row.text = text
+            row.expanded = True
         row.finish(EntryStatus.COMPLETED, self.clock())
         self._changed(row)
 

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/agent/conversation/transcript/turn.py

@@ -75,6 +75,7 @@ class TurnMixin(EntryLog):
                 outgoing=False,
                 by_agent=relayed.by_agent,
                 external=relayed.via == VIA_EXTERNAL,
+                group=relayed.group,
             )
         )
 
@@ -104,9 +105,15 @@ class TurnMixin(EntryLog):
             self.user_message(prompt, side=side)
         self.wait_for_model()
 
-    def wait_for_model(self) -> bool:
+    def wait_for_model(self, title: str = PROCESSING, *, tips: bool = True) -> bool:
         """Open the pinned wait row for a request, and report whether it opened.
 
+        Args:
+            title: What the row says is happening; ``Processing`` for a request, and a command's own words
+                (``Recap · writing``) for work it started that will take a while.
+            tips: Attach the deck's tip for a model request. A command's row is about the command, so it takes
+                none.
+
         Nothing is known about the response yet, and a call can take seconds, so
         the row goes up as soon as the request starts and stays for all of it:
         the loop calls the model again after every tool batch, and one row that
@@ -123,8 +130,8 @@ class TurnMixin(EntryLog):
         if any(self._is_open_row(entry) for entry in self.entries):
             return False
         self._turn_from = len(self.entries)
-        tips = self.tip_deck.next() if self.tip_deck is not None else ()
-        self._add(WaitEntry(id=self._next_id, title=PROCESSING, started_at=self.clock(), tips=tips))
+        shown = self.tip_deck.next() if tips and self.tip_deck is not None else ()
+        self._add(WaitEntry(id=self._next_id, title=title, started_at=self.clock(), tips=shown))
         return True
 
     def summarize_changes(self, workspace: PurePath | None = None) -> bool:

{zettcode-0.3.1 → zettcode-0.3.2}/src/zettcode/app/commands.py

@@ -77,6 +77,14 @@ class CommandHost(Protocol):
     def request_layout(self) -> None:
         """Ask for the screen to be laid out again, after a change in what it shows."""
 
+    async def wait_for_frame(self) -> None:
+        """Wait until the next frame has reached the terminal.
+
+        A command that has just put a row on screen and is about to start work
+        with no ``await`` in it asks for this first: the row is drawn before the
+        work begins instead of after it.
+        """
+
     def offer(self, command: str) -> None:
         """Put ``command`` and a space in the draft, which opens the menu of the words it takes."""
 
@@ -101,7 +109,7 @@ 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:
+    async def prompt(self, text: str, *, shown: str | None = None, cache: 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
@@ -120,6 +128,11 @@ class CommandHost(Protocol):
             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.
 
+            cache: How the turn may use the provider's prompt cache: ``"read_write"`` (the default) extends it for
+                the next turn, ``"read"`` reuses a warm prefix without marking this turn's new content, and
+                ``"off"`` sends no cache directive. A one-off report a reader is not going to follow is worth
+                ``"read"``.
+
         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
@@ -199,12 +212,21 @@ class CommandResult:
         relayout: Re-measure the widget tree after applying the result. Set it
             when the change affects geometry a fixed-height row already
             measured, such as the header showing a new model name.
+        intro: What a result that is still working is doing, in one line. The shell shows it in the pinned row
+            while it waits, which is how a command that takes seconds says so.
+        run: The rest of a result, when the command has not finished. The shell opens the pinned row with
+            ``intro``, awaits this, and shows what it returned; Ctrl-C, Escape, sending the next line, and Enter on an
+            empty draft stop it — a command that is working does not hold the composer. A command returns
+            this instead of awaiting the slow part itself, so the reader sees it working. The other fields of
+            *this* result are then names to the wind: only what ``run`` answers is applied.
     """
 
     message: str = ""
     notification: str | None = None
     widget: Widget | None = None
     relayout: bool = False
+    intro: str = ""
+    run: Awaitable[CommandResult] | None = None
 
 
 @dataclass(frozen=True, slots=True)