zettcode 0.1.11__tar.gz → 0.1.12__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.1.11
+Version: 0.1.12
 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

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

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

@@ -101,6 +101,26 @@ 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:
+        """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 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.
+
+        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.1.12}/src/zettcode/app/ui/app.py

@@ -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
@@ -254,7 +254,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 +659,26 @@ class ZettCodeApp(
             if outcome:
                 self._settle_wait(outcome)
 
+    async def prompt(self, text: str) -> 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.
+
+        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.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)
+        return True
+
     async def run_continue(self) -> None:
         """Pick up the request that was interrupted, where it stopped, as a turn of the conversation.
 
@@ -821,12 +840,6 @@ class ZettCodeApp(
             # 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
@@ -971,6 +984,7 @@ class ZettCodeApp(
         hint: str | None = None,
         *,
         relayed: Relayed | None = None,
+        advance: bool = True,
     ) -> None:
         """Stream one agent turn, keeping the task panel and transcript current.
 
@@ -1056,7 +1070,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.1.12}/src/zettcode/app/ui/messaging.py

@@ -1,8 +1,8 @@
-"""Messages between sessions: sending one with ``@``, receiving one as a turn.
+"""Messages between sessions: receiving one as a turn, and what the broker knows about this one.
 
 Another ZettCode session reaches this one through the broker (:mod:`zettcode.broker`), and this
-one reaches it. The shell's part is small, because a received message is meant to behave like one the
-reader typed:
+one reaches it through the model. The shell's receiving part is small, because a message is meant to
+behave like one the reader typed:
 
 * **Idle** — it starts a turn at once, drawn as a message from that session and not as the reader's
   own, and everything after is an ordinary turn: the wait row, the answer, the summary of what
@@ -10,9 +10,10 @@ reader typed:
 * **Busy** — it waits, and starts when the request in flight ends, after what the reader queued. It
   never steers the request: it came from somebody else, and "change what you are doing" is the
   reader's to say.
-* **Sending** — a draft that *begins* with ``@name`` of an active session is a message to it, not a
-  request to the model: it is sent, whatever this session is doing, and drawn as sent. A session named
-  later in the draft is only a reference the model is told about.
+
+The shell sends nothing itself. ``@name`` in a draft is resolved like any other reference
+(:mod:`zettcode.mentions`): the model reads which session it means and how to reach it, and calls
+``send_message`` itself when the request calls for one.
 
 The session also tells the broker what it is — its id, title, and whether it is busy — whenever one
 of them changes, so the others see a current list. None of this can fail the shell: with no broker the
@@ -22,29 +23,20 @@ shell is exactly what it was.
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
-from zettcode.broker.client import Receipt, SendError
-from zettcode.broker.protocol import MAX_TEXT, VIA_USER
-from zettcode.mentions import MENTION
-from zettcode.prompt import PromptPart, carries_image, plain_text
+from zettcode.broker.client import Receipt
 from zettcode.relay import Relayed
 
 from .shell import ShellState
 
 if TYPE_CHECKING:  # pragma: no cover - annotations only
-    from zettcode.broker.client import RosterEntry
-
     from ..agent.agent import SessionLink
 
 #: Messages from other sessions that may wait for a request to end. A session that is flooded refuses
 #: the rest, and the sender is told why, instead of this shell holding an unbounded list.
 MAX_INBOX = 16
 
-#: Characters that may separate ``@name`` from the message it addresses: ``@bob: hi`` and ``@bob, hi``.
-_SEPARATORS = " \t\r\n,:;"
-
 #: Characters of a waiting message that the notice repeats, so the reader can tell which one it is.
 _PREVIEW = 60
 
@@ -56,8 +48,6 @@ class MessagingMixin(ShellState):
     messenger: SessionLink | None
     #: Messages from other sessions waiting for the request in flight to end, oldest first.
     _inbox: list[Relayed]
-    #: Sends in flight, held so they are not collected and can be cancelled on exit.
-    _sends: set[asyncio.Task[None]]
     #: Whether the connection has been started; before that there is no loop to tell it anything on.
     _messaging_live: bool
     #: The session id the broker was last told about, to notice a switch.
@@ -82,14 +72,9 @@ class MessagingMixin(ShellState):
         self._messaging_start = asyncio.ensure_future(messenger.start())
 
     async def _stop_messaging(self) -> None:
-        """Leave the broker and end what is still being sent. Nothing here may delay leaving."""
+        """Leave the broker. Nothing here may delay leaving."""
         messenger = self.messenger
         self._messaging_live = False
-        sends = tuple(self._sends)
-        for send in sends:
-            send.cancel()
-        if sends:
-            await asyncio.gather(*sends, return_exceptions=True)
         start = self._messaging_start
         if start is not None:
             await asyncio.gather(start, return_exceptions=True)
@@ -179,68 +164,3 @@ class MessagingMixin(ShellState):
             return False
         self._start_relayed(self._inbox.pop(0))
         return True
-
-    # -- sending ----------------------------------------------------------------------------------
-    def _session_message(self, parts: Sequence[PromptPart]) -> tuple[str, str] | None:
-        """Return ``(name, text)`` when a draft is addressed to an active session, else ``None``.
-
-        A draft is addressed when its first word is ``@name`` and ``name`` is the handle of a session
-        that is active now. Anything else — a name nobody has, a name in the middle, a file path — is an
-        ordinary draft for the model.
-        """
-        messenger = self.messenger
-        if messenger is None:
-            return None
-        text = plain_text(parts).lstrip()
-        match = MENTION.match(text)
-        if match is None:
-            return None
-        peer = messenger.find(match.group(1))
-        if peer is None:
-            return None
-        return peer.handle, text[match.end() :].lstrip(_SEPARATORS).rstrip()
-
-    def _send_session_message(self, parts: Sequence[PromptPart]) -> bool | None:
-        """Send a draft addressed to a session, or say why it cannot be.
-
-        Returns:
-            ``None`` when the draft is not addressed to a session and the caller should treat it as any
-            other; otherwise what :meth:`submit` returns — ``True`` when the draft was taken and the
-            composer should clear, ``False`` when it was not and the draft stays to be fixed.
-        """
-        found = self._session_message(parts)
-        if found is None:
-            return None
-        name, text = found
-        if carries_image(parts):
-            self.flash(f"a message to @{name} is text only", level="error")
-            return False
-        if not text:
-            self.flash(f"write the message after @{name}", level="error")
-            return False
-        if len(text) > MAX_TEXT:
-            self.flash(f"a message is limited to {MAX_TEXT} characters; this is {len(text)}", level="error")
-            return False
-        peer = self.messenger.find(name) if self.messenger is not None else None
-        if peer is None:  # went away between the two lookups: nothing was addressed
-            return None
-        task = asyncio.create_task(self._deliver(peer, text))
-        self._sends.add(task)
-        task.add_done_callback(self._sends.discard)
-        return True
-
-    async def _deliver(self, peer: RosterEntry, text: str) -> None:
-        """Send one message and put the outcome in the conversation: the message, or why it was not taken."""
-        messenger = self.messenger
-        if messenger is None:
-            return
-        try:
-            delivered = await messenger.send(peer.session_id, text, via=VIA_USER)
-        except SendError as error:
-            self.transcript.error(f"not sent to @{peer.handle}: {error}")
-        except Exception as error:  # noqa: BLE001 - a bug here must not be silent, and must not end the shell
-            self.transcript.error(f"not sent to @{peer.handle}: {type(error).__name__}")
-        else:
-            note = "queued" if delivered.disposition == "queued" else "delivered"
-            self.transcript.sent_message(delivered.to.handle, text, note)
-        self.app.invalidate()

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

@@ -246,6 +246,10 @@ class ShellState:
     def submit(self, value: str, *, command: bool | None = None) -> bool | None:
         """Start a turn, steer the running one, or run a slash command (``command``: whether the draft is one)."""
 
+    async def prompt(self, text: str) -> bool:
+        """Run ``text`` as one turn, as if the reader had typed it; whether one was started and has ended."""
+        return False
+
     def flash(self, message: str, *, seconds: float = FLASH_SECONDS, level: str = "info") -> None:
         """Say something in the row above the composer, for a few seconds."""
 

{zettcode-0.1.11 → zettcode-0.1.12}/src/zettcode/config.py

@@ -461,8 +461,8 @@ class ZettCodeConfig:
         shell_network: Let a command that runs in the ``safe`` sandbox use the network. Off by default; ``[shell]
             network = true`` turns it on. ``full`` always has the network, and so does a machine with no sandbox.
         sessions_enabled: Register with the background session broker, so this session can be
-            messaged by the others and message them: ``@name`` in the composer and the
-            ``send_message`` and ``list_sessions`` tools.
+            messaged by the others and message them: ``@name`` in the composer names a
+            session for the model, and the ``send_message`` and ``list_sessions`` tools reach it.
         update_enabled: Ask PyPI, in the background, whether a newer release
             exists, and offer it on a later start.
         update_file: Where that check leaves what it found; one small JSON file.

{zettcode-0.1.11 → zettcode-0.1.12}/src/zettcode/mentions.py

@@ -173,9 +173,9 @@ class SkillMentions(MentionProvider):
 class SessionMentions(MentionProvider):
     """The other ZettCode sessions that are running, addressed by the name they are listed under.
 
-    A draft that *begins* with one of these is a message to that session and is sent there instead of
-    to the model (see :mod:`zettcode.app.ui.messaging`). A session named further along is only a
-    reference, which tells the model what the name means and that it can send a message to it.
+    A session named anywhere in a draft is a reference like any other: the model reads ``session "name"``
+    and is told how to reach that session, and decides for itself whether the request calls for a message.
+    The shell sends nothing itself (see :mod:`zettcode.app.ui.messaging`).
 
     Candidates are read from what the connection last reported — a list in memory — and never from
     the broker: completion runs on every keystroke after an ``@``.
@@ -240,11 +240,11 @@ class SessionMentions(MentionProvider):
         return next((peer for peer in self._peers() if peer.handle == name), None)
 
     def expand(self, name: str) -> str | None:
-        """Tell the model what the reader's ``@`` meant, for a draft that names a session inside a sentence.
+        """Tell the model what the reader's ``@`` meant and how to reach that session.
 
         Nothing is sent from here: the model is told which session the words mean and how to reach it, and
-        decides for itself whether the request calls for a message. A draft that *begins* with the name
-        never gets this far, because the shell sends it to that session itself.
+        decides for itself whether the request calls for a message. A draft that begins with the name is no
+        different from one that names the session inside a sentence.
         """
         peer = self._find(name)
         if peer is None:
@@ -254,10 +254,11 @@ class SessionMentions(MentionProvider):
         return (
             f'In the message above, `session "{name}"` is what the user wrote as @{name}. In ZettCode an @ before a '
             f"name means another ZettCode session that is running right now, not a file or a skill. This one works{where}.{about}\n"
-            f"If the user's request is for that session to do or know something, send it a message with the "
-            f'send_message tool: send_message(to="{peer.session_id}", message=...). Write the message so the '
-            f"other session can act on it without having seen this conversation. If the request is only about the "
-            f"session (what it is doing, where it is), list_sessions answers that. Do not send anything the "
+            f"When the user's message is addressed to that session — the @ begins the message — what follows the name "
+            f"is the message to pass on. When the session is only mentioned, decide whether the request is for it. "
+            f'To send, call the send_message tool: send_message(to="{peer.session_id}", message=...). Write the '
+            f"message so the other session can act on it without having seen this conversation. If the request is only "
+            f"about the session (what it is doing, where it is), list_sessions answers that. Do not send anything the "
             f"user did not ask you to pass on."
         )
 

{zettcode-0.1.11 → zettcode-0.1.12}/src/zettcode/relay.py

@@ -1,8 +1,8 @@
 """A message from another session: who sent it, what the model reads, and how it is stored.
 
-Another ZettCode session on the same machine can send this one a message, either because its reader
-typed ``@name …`` there or because its agent used the ``send_message`` tool. In *this* session the
-message is handled like one the reader typed — it is a turn, it is stored, it is restored with the
+Another ZettCode session on the same machine can send this one a message because its agent used the
+``send_message`` tool. In *this* session the message is handled like one the reader typed — it is a
+turn, it is stored, it is restored with the
 session — with three differences, all of them here:
 
 * the model is told where it came from, so it does not mistake a colleague's request for its own

{zettcode-0.1.11 → zettcode-0.1.12}/src/zettcode/sdk/client.py

@@ -628,7 +628,7 @@ class Client:
         )
 
     async def send(self, to: str, text: str) -> Delivered:
-        """Send a message to another ZettCode session, as the terminal's ``@name`` draft does.
+        """Send a message to another ZettCode session without going through this session's model.
 
         Args:
             to: The session's handle, or its id.

{zettcode-0.1.11 → zettcode-0.1.12}/src/zettcode/server/app.py

@@ -570,7 +570,7 @@ def create_app(settings: Settings, *, client_factory: ClientFactory | None = Non
 
     @protected.post("/sessions/current/send", response_model=SentOut, tags=["sessions"])
     async def send_message(body: SendIn, runner: RunnerDep) -> SentOut:
-        """Send a message to another ZettCode session, as a draft beginning with ``@name`` does."""
+        """Send a message to another ZettCode session explicitly, without a model turn."""
         to, disposition = await runner.send(body.to, body.text)
         return SentOut(to=to, disposition=disposition)