zettcode-messaging 0.4.1__tar.gz

zettcode_messaging-0.4.1/.gitignore

@@ -0,0 +1,37 @@
+**/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.smoke/
+.coverage
+**/.pytest_cache/
+**/.ruff_cache/
+.zett-tool-output/
+.env
+.DS_Store
+
+# viztracer writes its trace here by default.
+/result.json
+
+# The docs site: dependencies, build output, and VitePress' cache.
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
+# The gateway's page is built from clients/gateway into the package when a distribution is made (`make gateway-ui`);
+# the build output is not kept in the repository. pyproject's `artifacts` puts it in the wheel all the same.
+packages/zettcode-gateway/src/zettcode/gateway/static/
+
+# The palette gallery is generated by `make palettes`: every widget painted in
+# every palette, written by docs/scripts/palette_gallery.py. Regenerate it
+# rather than committing a 2 MB copy that goes stale the moment a colour moves.
+docs/internal/palettes.html
+
+# The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
+packages/order.txt

zettcode_messaging-0.4.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: zettcode-messaging
+Version: 0.4.1
+Summary: Talking to the other ZettCode sessions — the messaging tools and the line to the broker — as a part of the agent that lives apart from it
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,messaging,zettcode
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zett-agent<0.3,>=0.2.7
+Requires-Dist: zettcode-broker
+Requires-Dist: zettcode-engine

zettcode_messaging-0.4.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "zettcode-messaging"
+description = "Talking to the other ZettCode sessions — the messaging tools and the line to the broker — as a part of the agent that lives apart from it"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "messaging", "agent"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [
+  # The plugin base classes, the service names, and the modes a message is sent with.
+  "zettcode-engine",
+  # The protocol, the client and the errors the tools speak.
+  "zettcode-broker",
+  # The tools this subclasses.
+  "zett-agent>=0.2.7,<0.3",
+]
+
+# A part of the program, not a plugin: the `zettcode.plugins` group is what the plugin release line looks for.
+[project.entry-points."zettcode.agent"]
+messaging = "zettcode.messaging.plugin:Messaging"
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# One version for the whole repository: the engine ships the file.
+path = "../zettcode-engine/src/zettcode/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

zettcode_messaging-0.4.1/src/zettcode/messaging/__init__.py

@@ -0,0 +1,13 @@
+"""Talking to the other ZettCode sessions: the tools, the line to the broker, and later the inbox.
+
+A part of the program that lives in a distribution of its own, found through the ``zettcode.agent`` entry point. The
+runtime hands it the line to the broker by name (``MESSENGER``); without one it registers nothing, which is the case in
+a program that never joins the sessions.
+"""
+
+from __future__ import annotations
+
+from .messenger import Messenger
+from .plugin import Messaging
+
+__all__ = ["Messenger", "Messaging"]

zettcode_messaging-0.4.1/src/zettcode/messaging/extension.py

@@ -0,0 +1,281 @@
+"""The tools that let the model talk to the other ZettCode sessions running on this machine.
+
+``list_sessions`` says who is there, and which group chats this session may write to; ``send_message`` hands one of
+them a message, or every member of a group; ``message_history`` reads what this session and another one (or a group)
+said to each other before, from the broker's persistent store; ``manage_group`` makes and changes group chats. The other session
+receives it as a turn of its own — drawn there as a message from this session, with this session's
+id so that it can answer — and this call returns as soon as it has taken the message, not when it has
+finished with it. A message asks for one of two things while that session is busy: it can be handed to
+the request it is running (``mode="steer"``, the default) or wait until that request ends
+(``mode="followup"``); an idle session starts a turn either way. What it does about the message is its
+own agent's business, and its answer, if any, arrives here as a message of its own.
+
+All are request-scoped like every tool: they are registered for each request, and a request that is a side
+question keeps only ``list_sessions`` and ``message_history`` (see :mod:`zettcode.engine.dialogue.side`), because
+sending a message is not reading.
+"""
+
+from __future__ import annotations
+
+import time
+
+from zett_agent.agent import AgentRunContext
+from zett_agent.extensions.base import AgentExtension
+from zett_agent.tools.base import AgentTool, tool
+
+from zettcode.broker.client import SendError
+from zettcode.broker.protocol import VIA_AGENT
+from zettcode.modes import MODE_STEER, MODES
+
+from .messenger import Messenger
+
+LIST_SESSIONS_TOOL_NAME = "list_sessions"
+SEND_MESSAGE_TOOL_NAME = "send_message"
+MESSAGE_HISTORY_TOOL_NAME = "message_history"
+MANAGE_GROUP_TOOL_NAME = "manage_group"
+
+#: The most characters of one stored message ``message_history`` shows; a longer one is cut, with its length.
+HISTORY_TEXT = 600
+
+#: What a refused send says, by the reason the broker gave, for the ones a model can do something about.
+_ADVICE = {
+    "unknown": "No such session is active. Call list_sessions to see who is.",
+    "ambiguous": "More than one session matches. Use the session id from list_sessions.",
+    "self": "That is this session; a message to yourself is not sent.",
+    "loop": "This conversation between sessions has gone on long enough; stop replying and tell your user.",
+    "rate": "Too many messages were sent in a short time. Wait before sending another.",
+    "offline": "The session broker is not running, so no other session can be reached right now.",
+    "denied": "You are not a member of that group. list_sessions shows the groups you may write to.",
+    "gone": "Nobody there is connected right now.",
+    "internal": "The broker failed while delivering that. Try again; if it keeps failing, tell your user.",
+}
+
+
+def _sentence(error: SendError) -> str:
+    """Return what the model is told when a message did not arrive."""
+    advice = _ADVICE.get(error.reason)
+    if advice is None:
+        return str(error)
+    # Offline has nothing to add to what the advice says; the others carry the broker's own detail.
+    return advice if error.reason == "offline" else f"{str(error).rstrip('.')}. {advice}"
+
+
+class SessionMessagingExtension(AgentExtension):
+    """Register ``list_sessions`` and ``send_message`` for a messenger."""
+
+    def __init__(self, messenger: Messenger) -> None:
+        """Keep the messenger the tools talk through."""
+        self.messenger = messenger
+
+    async def on_tool(self, context: AgentRunContext) -> None:
+        """Register both tools for this request."""
+        context.register_tool(self._list_tool())
+        context.register_tool(self._send_tool())
+        context.register_tool(self._history_tool())
+        context.register_tool(self._group_tool())
+
+    def _list_tool(self) -> AgentTool:
+        """Create the tool that lists the other active sessions."""
+        messenger = self.messenger
+
+        @tool(name=LIST_SESSIONS_TOOL_NAME)
+        async def list_sessions() -> str:
+            """List the other ZettCode sessions that are running on this machine right now, and the group chats
+            this session is a member of (the only ones it may write to).
+            Each session line gives the name to address it by, its id, what it is about, whether it is idle or working,
+            and the directory it works in; each group line gives #name and its members. Sessions come and go, so the
+            list is only true now.
+
+            Snippet:
+                list_sessions()
+
+            Guidelines:
+                - Call this before send_message when you do not already know the id of the session to message.
+                - A session that is working still receives a message; it handles it when its current request ends.
+                - Other sessions belong to the same user, but each one has its own conversation and its own files in mind.
+            """
+            others = messenger.peers()
+            groups = messenger.groups()
+            if not others and not groups:
+                if messenger.connected:
+                    return "No other ZettCode session is running."
+                return "No other session can be seen: the session broker is not running."
+            lines = []
+            if others:
+                lines.append(f"{len(others)} other session{'s' if len(others) != 1 else ''}:")
+            else:
+                lines.append("No other ZettCode session is running.")
+            for entry in others:
+                about = f'"{entry.title}"' if entry.title else "untitled"
+                lines.append(f"- {entry.handle} (id {entry.session_id}) {about}, {entry.status}, in {entry.workspace}")
+            if groups:
+                names = {entry.session_id: entry.handle for entry in messenger.client.roster}
+                lines.append(f"{len(groups)} group chat{'s' if len(groups) != 1 else ''} you may write to:")
+                for group in groups:
+                    members = ", ".join(names.get(m, f"{m[:8]} (offline)") for m in group.members)
+                    lines.append(f"- #{group.name}: {members}")
+            return "\n".join(lines)
+
+        return list_sessions
+
+    def _send_tool(self) -> AgentTool:
+        """Create the tool that sends a message to another active session."""
+        messenger = self.messenger
+
+        @tool(name=SEND_MESSAGE_TOOL_NAME)
+        async def send_message(to: str = "", message: str = "", mode: str = MODE_STEER, group: str = "") -> str:
+            """Send a message to another running ZettCode session, or to every other member of a group chat you are
+            in. The receiver gets it as a request of its own. Returns once they have taken the message, not once
+            they have acted on it: a reply, if one is sent, arrives later as a message to you. Every message costs its
+            receiver a turn, so send one only when it changes what they will do.
+
+            Args:
+                message: What to tell them. They cannot see this conversation, so say everything they need: what you
+                    want, which files or facts matter, and what a useful answer looks like.
+                to: The session to message: its id from list_sessions, or the name listed beside it. Give this or group.
+                group: A group chat to write to instead, such as "review" (as listed by list_sessions, without the
+                    #). Every other member that is connected receives the message, and everyone can read it.
+                mode: What a busy receiver should do. "steer" (the default) hands the message to the request it is
+                    running, so it changes course now; "followup" waits until that request ends. A session that is
+                    idle starts on the message either way.
+
+            Snippet:
+                send_message(to="fix-parser", message="The tokenizer change is merged; please rerun your tests.")
+                send_message(to="fix-parser", message="Also check the tab case.", mode="followup")
+                send_message(group="review", message="Round one is done; findings are in docs/review.md.")
+
+            Guidelines:
+                - Send a message only when your user asked you to, or when the work needs something only another session can do.
+                - The receiver cannot see this conversation, so write a message that stands on its own.
+                - Do not send the same message twice; a message that was taken is being handled.
+                - Reply only when the message needs an answer: it asks a question, asks you to do something, or you have a result, a blocker or a decision the sender is waiting for. Otherwise stay silent.
+                - Never send thanks, "got it", "ok", "done", "bye" or any other closing courtesy, and do not answer one you receive: a conversation ends when nobody needs anything more, and replying to a goodbye starts a loop that costs tokens for both sides.
+                - When the work is finished, send one message with the result if someone is waiting for it, then stop. Do not confirm that you sent it.
+                - Write to a group only when all of its members need to know; otherwise message one session. In a group, do not reply just because you were addressed: answer only when you are the one who has what was asked for, and never echo agreement that others have already given.
+                - Your answer to your own user is not sent to the other session; only this tool sends anything.
+            """
+            if mode not in MODES:
+                raise ValueError("mode is 'steer' or 'followup'")
+            if not message.strip():
+                raise ValueError("a message needs some text")
+            if bool(to) == bool(group):
+                raise ValueError("give exactly one of 'to' (a session) or 'group' (a group chat)")
+            try:
+                if group:
+                    sent = await messenger.send_group(group, message, via=VIA_AGENT, mode=mode)
+                    names = ", ".join(peer.handle for peer, _ in sent.delivered)
+                    note = f"; not delivered to {', '.join(h for h, _ in sent.failed)}" if sent.failed else ""
+                    return f"Delivered to #{sent.group}: {names}{note}."
+                delivered = await messenger.send(to, message, via=VIA_AGENT, mode=mode)
+            except SendError as error:
+                raise ValueError(_sentence(error)) from error
+            peer = delivered.to
+            said = {
+                "started": "started on it now",
+                "steered": "steered it into the request it was running",
+                "queued": "queued it until its current request ends",
+                "delivered": "delivered it to that session's chat window",
+                "held": "kept it for that session, whose inbox is full, and the broker delivers it when there is room",
+            }.get(delivered.disposition, "took it")
+            return f"Delivered to {peer.handle} (id {peer.session_id}); it {said}."
+
+        return send_message
+
+    def _history_tool(self) -> AgentTool:
+        """Create the tool that reads what was said before."""
+        messenger = self.messenger
+
+        @tool(name=MESSAGE_HISTORY_TOOL_NAME)
+        async def message_history(session: str = "", group: str = "", limit: int = 20) -> str:
+            """Read the messages this session exchanged earlier with one other session, or what was said in a group
+            chat you are in. The broker keeps them across restarts, so this also shows what was said before either
+            session was restarted. You see only your own conversations.
+
+            Args:
+                session: The other session: its name or id, from list_sessions or from an earlier message. Give this
+                    or group, or neither to see your most recent messages with everyone.
+                group: A group chat you are in, such as "review".
+                limit: How many of the newest messages to show, 1 to 100 (default 20).
+
+            Snippet:
+                message_history(session="fix-parser")
+                message_history(group="review", limit=50)
+
+            Guidelines:
+                - Use it to recall what you and another session already agreed before you write to them again.
+                - Messages are shown oldest first; a long one is cut.
+            """
+            if session and group:
+                raise ValueError("give 'session' or 'group', not both")
+            try:
+                messages, _ = await messenger.history(with_=session, group=group, limit=max(1, min(limit, 100)))
+            except SendError as error:
+                raise ValueError(_sentence(error)) from error
+            if not messages:
+                return "No messages yet."
+            me = messenger.client.session.session_id if messenger.client.session is not None else ""
+            lines = [f"{len(messages)} message{'s' if len(messages) != 1 else ''}, oldest first:"]
+            for item in messages:
+                sender = item.get("from", {})
+                to = item.get("to", {})
+                who = "you" if sender.get("session_id") == me else f"@{sender.get('handle', '?')}"
+                if to.get("kind") == "group":
+                    where = f"#{to.get('name', '?')}"
+                else:
+                    where = "you" if to.get("session_id") == me else f"@{to.get('handle', '?')}"
+                text = str(item.get("text", ""))
+                if len(text) > HISTORY_TEXT:
+                    text = f"{text[:HISTORY_TEXT]}... [{len(text)} characters]"
+                when = time.strftime("%Y-%m-%d %H:%M", time.localtime(float(item.get("ts", 0))))
+                lines.append(f"[{when}] {who} -> {where}: {text}")
+            return "\n".join(lines)
+
+        return message_history
+
+    def _group_tool(self) -> AgentTool:
+        """Create the tool that makes and changes group chats."""
+        messenger = self.messenger
+
+        @tool(name=MANAGE_GROUP_TOOL_NAME)
+        async def manage_group(action: str, group: str, members: str = "") -> str:
+            """Create or change a group chat of sessions. A message sent to a group (send_message with group=...)
+            reaches every other member that is connected. You become a member of a group you create, and only a
+            member may write to it or change it.
+
+            Args:
+                action: "create" (new group with you and the members), "add" (add members), "remove" (remove members),
+                    "leave" (take yourself out), or "delete" (remove the group; what was said stays in the history).
+                group: The group's name: letters, digits, '-' or '_', such as "review".
+                members: For create, add and remove: session names or ids from list_sessions, separated by commas.
+
+            Snippet:
+                manage_group(action="create", group="review", members="fix-parser, docs")
+                manage_group(action="leave", group="review")
+
+            Guidelines:
+                - Create a group only when your user asked for one, or when several sessions work on one task together.
+                - A group with no member left is deleted.
+            """
+            names = [part.strip() for part in members.split(",") if part.strip()]
+            try:
+                found = await messenger.manage_group(action, group, names)
+            except SendError as error:
+                raise ValueError(_sentence(error)) from error
+            if found is None:
+                return f"Group #{group.lstrip('#').lower()} no longer exists."
+            roster = {entry.session_id: entry.handle for entry in messenger.client.roster}
+            who = ", ".join(roster.get(m, f"{m[:8]} (offline)") for m in found.members)
+            return (
+                f"Group #{found.name} has {len(found.members)} member{'s' if len(found.members) != 1 else ''}: {who}."
+            )
+
+        return manage_group
+
+
+__all__ = [
+    "LIST_SESSIONS_TOOL_NAME",
+    "MANAGE_GROUP_TOOL_NAME",
+    "MESSAGE_HISTORY_TOOL_NAME",
+    "SEND_MESSAGE_TOOL_NAME",
+    "SessionMessagingExtension",
+]

zettcode_messaging-0.4.1/src/zettcode/messaging/inbox.py

@@ -0,0 +1,206 @@
+"""The inbox: what an event outside the conversation hands the agent, steered in or queued for the next turn.
+
+The engine's :class:`~zettcode.engine.delivery.Delivery` knows two things — whether a request is running, and how to
+hand a message to it — but not what to do with a message that arrives when nothing runs. That is this class: a steer
+goes straight into the request; anything else waits, in order, and the front end that owns the turn loop starts the next
+one when the inbox says so (``start_with``), which is the same starter it uses for a reader's prompt.
+
+This is the one queue. A message another session sent (see :mod:`zettcode.messaging.relay`) is a :class:`Waiting` whose
+``payload`` is that message: the front-end starter hands it back to the code that knows how to run it, and messages that
+waited in a window that was busy are answered together, as one turn, the way the broker has always done it.
+
+The queue is one per runtime, provided as the ``INBOX`` service, so the broker's incoming path, a trigger and a program
+using the SDK all deliver the same way and cannot start two turns at once.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from zettcode.engine.delivery import Delivery
+from zettcode.modes import MODE_STEER, MODES
+from zettcode.relay import Relayed, batch_size, merge
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zett_agent.messages import UserMessage
+
+__all__ = ["FULL", "INBOX", "MAX_WAITING", "QUEUED", "STARTED", "STEERED", "Inbox", "Waiting"]
+
+#: The service name the inbox is provided under, for a front end that delivers into the agent.
+INBOX = "inbox"
+
+#: How many messages may wait; the rest are refused (:data:`FULL`) and the broker offers them again later.
+MAX_WAITING = 64
+
+#: What ``deliver`` did: the running request took it, it was queued, a turn was started with it, or there was no room.
+STEERED = "steered"
+QUEUED = "queued"
+STARTED = "started"
+FULL = "full"
+
+
+@dataclass(frozen=True, slots=True)
+class Waiting:
+    """One message the inbox holds for the next turn.
+
+    Attributes:
+        message: What to run: text, or a message when it carries pictures.
+        hint: Text appended after it, as for a prompt.
+        origin: Where it came from, for the transcript and the stored message.
+        payload: What the front end needs to run it its own way — the
+            :class:`~zettcode.relay.Relayed` a message from another session came in as, or ``None`` for a plain event.
+    """
+
+    message: str | UserMessage
+    hint: str | None = None
+    origin: str = "event"
+    payload: object | None = None
+
+
+class Inbox:
+    """Steer the request in flight, or hold messages until one ends and a front end can start the next turn.
+
+    Args:
+        delivery: The runtime's delivery: whether a request runs, and how a message reaches it.
+        cap: How many may wait. The rest are refused with :data:`FULL`, which the broker turns into "busy, offer it
+            again", so a front end never holds an unbounded list.
+    """
+
+    def __init__(self, delivery: Delivery, *, cap: int = MAX_WAITING) -> None:
+        self._delivery = delivery
+        self._cap = cap
+        self._waiting: list[Waiting] = []
+        self._starter: Callable[[Waiting], bool] | None = None
+        self._forget: Callable[[], None] | None = None
+
+    @property
+    def waiting(self) -> tuple[Waiting, ...]:
+        """Return the messages held for the next turn, in the order they arrived."""
+        return tuple(self._waiting)
+
+    @property
+    def full(self) -> bool:
+        """Return whether the queue is at its cap, so a new message would be refused."""
+        return len(self._waiting) >= self._cap
+
+    def start_with(self, starter: Callable[[Waiting], bool]) -> None:
+        """Register what starts a turn from a waiting message, and drain anything already waiting.
+
+        The front end that owns the turn loop passes its own starter — the one a reader's prompt goes through — so a
+        follow-up is an ordinary turn and not a second kind of run. A starter that returns ``False`` says it could not
+        start one now; the message then stays waiting for the next end of a request.
+
+        Args:
+            starter: Called with one :class:`Waiting`; ``True`` once a turn is under way.
+        """
+        self._starter = starter
+        if self._waiting and not self._delivery.busy:
+            self._drain()
+
+    def deliver(
+        self,
+        message: str | UserMessage,
+        *,
+        mode: str = MODE_STEER,
+        hint: str | None = None,
+        origin: str = "event",
+        payload: object | None = None,
+    ) -> str:
+        """Hand one message to the agent, as a steer or as the next turn.
+
+        Args:
+            message: Text, or a message when it carries pictures (see :meth:`zettcode.engine.agent.ZettCodeAgent.turn`).
+            mode: ``"steer"`` (the default) hands it to the request that runs, so it changes course;
+                ``"followup"`` waits until that request ends. An idle agent starts a turn either way.
+            hint: Text appended after a follow-up turn, as for a normal prompt.
+            origin: Where it came from, for the transcript and the stored message.
+            payload: What a front end needs to run it its own way; a message from another session passes the
+                :class:`~zettcode.relay.Relayed`, which the starter hands back to the code that frames it.
+
+        Returns:
+            :data:`STEERED`, :data:`QUEUED`, :data:`STARTED` or :data:`FULL`.
+
+        Raises:
+            ValueError: When ``mode`` is neither ``"steer"`` nor ``"followup"``.
+        """
+        if mode not in MODES:
+            raise ValueError(f"mode is 'steer' or 'followup' (got {mode!r})")
+        if mode == MODE_STEER and self._delivery.busy and self._delivery.steer(message) is not None:
+            return STEERED
+        if self.full:
+            return FULL
+        self._waiting.append(Waiting(message, hint, origin, payload))
+        if self._delivery.busy:
+            self._arm()
+            return QUEUED
+        return STARTED if self._drain() else QUEUED
+
+    def requeue(self, items: Sequence[Waiting]) -> None:
+        """Put messages back that were already accepted, past the cap if it takes it.
+
+        The cap is for what new senders may add; a message the front end had already taken — a steer the running
+        request never read — must not be lost to a full queue. They keep their place at the end, in order.
+        """
+        self._waiting.extend(items)
+        if self._delivery.busy:
+            self._arm()
+        else:
+            self._drain()
+
+    def drain(self) -> bool:
+        """Start the next waiting turn if the front end is free; say whether anything is left waiting."""
+        return self._drain()
+
+    def _arm(self) -> None:
+        """Ask the runtime to tell the inbox when the last request ends, once — only while one runs.
+
+        Arming while nothing runs would be the same as calling back at once, and the drain that follows would arm
+        again: the queue waits for the next end of a request, which is what ``start_with`` and the next ``deliver``
+        look at instead.
+        """
+        if self._forget is None and self._delivery.busy:
+            self._forget = self._delivery.when_idle(self._woke)
+
+    def _woke(self) -> None:
+        """The request ended: drain what waited, and arm again if anything is left."""
+        self._forget = None
+        self._drain()
+
+    def _drain(self) -> bool:
+        """Start one turn from the queue, if a starter exists and nothing runs.
+
+        One at a time, and not one per call of this method only: a starter that schedules the turn instead of running
+        it (the SDK's creates a task) returns before the runtime is busy, so the loop must not look at ``busy`` again —
+        the next start waits for the next request to end, as the queue's ``waiting`` order promises.
+
+        Two messages another session sent, waiting one after the other, start as one turn: a window that was busy
+        answers them together instead of once per message (see :func:`~zettcode.relay.batch_size`). A plain event is
+        always a turn of its own.
+        """
+        while self._waiting and self._starter is not None and not self._delivery.busy:
+            item, taken = self._next()
+            if not self._starter(item):
+                break
+            del self._waiting[:taken]
+            break
+        if self._waiting:
+            self._arm()
+        return not self._waiting
+
+    def _next(self) -> tuple[Waiting, int]:
+        """Return the waiting item to start next, and how many of the queue's head it stands for."""
+        head = self._waiting[0]
+        if not isinstance(head.payload, Relayed):
+            return head, 1
+        run: list[Relayed] = []
+        for item in self._waiting:
+            if not isinstance(item.payload, Relayed):
+                break
+            run.append(item.payload)
+        count = batch_size(run)
+        if count <= 1:
+            return head, 1
+        merged = merge(run[:count])
+        return Waiting(merged.text, head.hint, head.origin, merged), count

zettcode_messaging-0.4.1/src/zettcode/messaging/messenger.py

@@ -0,0 +1,299 @@
+"""This session's line to the others: who is active, a message sent, a message received.
+
+The broker client (:mod:`zettcode.broker.client`) knows the wire; this is the part the rest of the
+application holds. The shell tells it what the session is now and gives it a place to hand a received
+message to, and the ``send_message`` tool and the ``@`` completion ask it who else is there.
+
+It owns one fact the client cannot know: which message the running turn is answering. An agent that
+is answering another agent carries that message's hop count on, which is what stops two sessions
+that keep replying to each other; a turn that began with the reader's own words starts at none.
+
+Nothing here blocks or raises into the shell. Without a broker every method answers as if nobody
+else were running, and a send says so.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from zettcode.broker.client import BrokerClient, Delivered, Incoming, Receipt, RosterEntry, SessionInfo
+from zettcode.broker.models import GroupDelivered, GroupInfo
+from zettcode.broker.protocol import VIA_AGENT, ImageData
+from zettcode.config import ZettCodeConfig
+from zettcode.modes import MODE_STEER
+from zettcode.relay import Relayed
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from pathlib import Path
+
+
+#: How long pieces of text are gathered before they are sent as one, so a stream is a few lines a second and not one per token.
+STREAM_BATCH = 0.06
+
+#: The most characters of text sent in one stream line, well inside what the broker passes (see ``MAX_STREAM``).
+STREAM_CHUNK = 4000
+
+
+class Messenger:
+    """The shell's and the agent's one handle on the other sessions."""
+
+    def __init__(self, client: BrokerClient | None = None, *, workspace: str | Path = "") -> None:
+        """Wrap a client; one is built for the default broker when none is given.
+
+        Args:
+            client: The connection to use. Its callbacks are taken over, so give a client that nothing
+                else is listening to.
+            workspace: The directory this session works in, which other sessions are shown.
+        """
+        self.workspace = str(workspace)
+        self.client = client if client is not None else BrokerClient()
+        self.client.on_message = self._received
+        self.client.on_roster = self._roster_changed
+        self.client.on_conflict = self._conflicted
+        self.client.on_problem = self._troubled
+        #: Where a received message goes; the shell sets it. It returns what this session says to the
+        #: sender: whether it took the message, and what will become of it.
+        self.receiver: Callable[[Relayed], Receipt] | None = None
+        #: Called, on the loop, whenever the roster or the connection changes, so a view can repaint.
+        self.on_change: Callable[[], None] | None = None
+        #: Called with a sentence when another process holds this session's id, and with ``None`` after.
+        self.on_conflict: Callable[[str | None], None] | None = None
+        #: Called with a sentence when the broker has been out of reach for a while, and with ``None`` when it is back.
+        self.on_problem: Callable[[str | None], None] | None = None
+        #: The message the running turn answers, if it answers one.
+        self.answering: Relayed | None = None
+        #: Whether a message the sender marked ``direct`` is run as this session's own prompt; said in the roster.
+        self.direct = False
+        self._started = False
+        self._piece: tuple[str, list[str]] | None = None
+        self._flush: asyncio.TimerHandle | None = None
+
+    @classmethod
+    def create(cls, config: ZettCodeConfig) -> Messenger | None:
+        """Return the messenger this configuration asks for, or ``None`` when sessions are switched off."""
+        if not config.sessions_enabled:
+            return None
+        return cls(workspace=config.workspace)
+
+    # -- the life of the connection ---------------------------------------------------------------
+    @property
+    def started(self) -> bool:
+        """Return whether :meth:`start` has run, which is when it is safe to tell it about the session."""
+        return self._started
+
+    async def start(self) -> None:
+        """Begin connecting in the background. Returns at once, whether or not a broker exists."""
+        self._started = True
+        await self.client.start()
+
+    async def close(self) -> None:
+        """Leave the broker. Quick, and safe to call twice."""
+        self._started = False
+        self.receiver = None
+        await self.client.close()
+
+    # -- what this session is ---------------------------------------------------------------------
+    def describe(self, session_id: str, title: str | None, *, busy: bool) -> None:
+        """Say what this session is now. Cheap when nothing changed, so callers need not check.
+
+        Args:
+            session_id: The active session.
+            title: Its title, or ``None`` while it has none.
+            busy: Whether a request or command is running.
+        """
+        info = SessionInfo(
+            session_id=session_id,
+            title=title or "",
+            workspace=self.workspace,
+            status="working" if busy else "idle",
+            direct=self.direct,
+        )
+        current = self.client.session
+        if current is not None and (current.session_id, current.title, current.status, current.direct) == (
+            info.session_id,
+            info.title,
+            info.status,
+            info.direct,
+        ):
+            return
+        self.client.set_session(info)
+
+    def retire(self) -> None:
+        """Say that this process has no session to be reached at: it only shows one that another process has open."""
+        if self.client.session is not None:
+            self.client.set_session(None)
+
+    # -- the others -------------------------------------------------------------------------------
+    @property
+    def connected(self) -> bool:
+        """Return whether the broker is reachable right now."""
+        return self.client.connected
+
+    @property
+    def conflict(self) -> str | None:
+        """Return why this session is not registered, or ``None``."""
+        return self.client.conflict
+
+    @property
+    def handle(self) -> str:
+        """Return the name the others call this session by, or ``""`` before it is registered."""
+        mine = self.client.session
+        if mine is None:
+            return ""
+        return next((entry.handle for entry in self.client.roster if entry.session_id == mine.session_id), "")
+
+    def peers(self) -> tuple[RosterEntry, ...]:
+        """Return the other active sessions, from memory: this is called as a draft is typed."""
+        return self.client.others()
+
+    def groups(self) -> tuple[GroupInfo, ...]:
+        """Return the group chats this session may write to, from memory."""
+        return self.client.groups
+
+    async def manage_group(self, action: str, name: str, members: list[str] | None = None) -> GroupInfo | None:
+        """Create a group, change who is in it, leave it or delete it (see :meth:`BrokerClient.manage_group`)."""
+        return await self.client.manage_group(action, name, members)
+
+    async def join_group(self, name: str) -> GroupInfo | None:
+        """Put this session in a group as the broker's owner may (see :meth:`BrokerClient.join_group`)."""
+        return await self.client.join_group(name)
+
+    async def history(self, *, with_: str = "", group: str = "", limit: int = 20) -> tuple[list[dict[str, Any]], str]:
+        """Return stored messages with one session, in a group, or all this session's own (see the client)."""
+        return await self.client.history(with_=with_, group=group, limit=limit)
+
+    # -- watching a turn --------------------------------------------------------------------------
+    @property
+    def on_stream(self) -> Callable[[str, dict[str, Any]], None] | None:
+        """Called with a watched session's id and one thing its turn said."""
+        return self.client.on_stream
+
+    @on_stream.setter
+    def on_stream(self, callback: Callable[[str, dict[str, Any]], None] | None) -> None:
+        self.client.on_stream = callback
+
+    def watch(self, session_id: str) -> None:
+        """Ask to be told what a session's turns say as they happen."""
+        self.client.watch(session_id)
+
+    def unwatch(self, session_id: str) -> None:
+        """Stop being told."""
+        self.client.unwatch(session_id)
+
+    def stream(self, kind: str, **fields: Any) -> None:
+        """Say one thing about the running turn to whoever watches it; a no-op when nobody does.
+
+        Pieces of text are gathered for :data:`STREAM_BATCH` seconds and go as one; anything else sends what was
+        gathered first, so the order is the order they happened in.
+        """
+        if not self.client.watched:
+            self._piece = None
+            if self._flush is not None:
+                self._flush.cancel()
+                self._flush = None
+            return
+        if kind in ("text", "thinking"):
+            text = fields.get("text", "")
+            if self._piece is not None and self._piece[0] != kind:
+                self._send_piece()
+            if self._piece is None:
+                self._piece = (kind, [])
+            self._piece[1].append(text)
+            if self._flush is None:
+                self._flush = asyncio.get_running_loop().call_later(STREAM_BATCH, self._send_piece)
+            return
+        self._send_piece()
+        self.client.publish({"t": kind, **fields})
+
+    def _send_piece(self) -> None:
+        if self._flush is not None:
+            self._flush.cancel()
+            self._flush = None
+        piece, self._piece = self._piece, None
+        if piece is None:
+            return
+        kind, parts = piece
+        if kind != "text":
+            self.client.publish({"t": kind})
+            return
+        # A burst of text is cut into lines the broker will pass: one longer than it allows is dropped there, whole.
+        text = "".join(parts)
+        for start in range(0, len(text), STREAM_CHUNK):
+            self.client.publish({"t": "text", "text": text[start : start + STREAM_CHUNK]})
+
+    # -- sending ----------------------------------------------------------------------------------
+    async def send(
+        self,
+        to: str,
+        text: str,
+        *,
+        via: str = VIA_AGENT,
+        direct: bool = False,
+        mode: str = MODE_STEER,
+        images: Sequence[ImageData] = (),
+    ) -> Delivered:
+        """Send a message and return once the other session has taken it.
+
+        A message sent by this session's agent while it is answering another one carries that message's
+        hop count on; a message the reader sent starts again at none.
+
+        Args:
+            to: The session's handle or id.
+            text: What to say.
+            via: How it came: the agent's tool, or the reader.
+            direct: Ask a session that can to run it as its own reader's prompt and answer the sender.
+            mode: What a busy recipient does with it: ``"steer"`` (the default) hands it to the running request,
+                ``"followup"`` waits until that request ends.
+            images: Pictures to send with a ``direct`` message.
+
+        Raises:
+            SendError: Nobody was reached, and why.
+        """
+        hops = self.answering.hops if self.answering is not None and via == VIA_AGENT else 0
+        return await self.client.send(to, text, hops=hops, via=via, direct=direct, mode=mode, images=images)
+
+    async def send_group(
+        self, group: str, text: str, *, via: str = VIA_AGENT, mode: str = MODE_STEER
+    ) -> GroupDelivered:
+        """Write to a group chat this session is in; the hop count is carried on as for :meth:`send`.
+
+        Raises:
+            SendError: Nobody was reached, and why (``denied`` when this session is not in the group).
+        """
+        hops = self.answering.hops if self.answering is not None and via == VIA_AGENT else 0
+        return await self.client.send_group(group, text, hops=hops, via=via, mode=mode)
+
+    # -- what the client reports ------------------------------------------------------------------
+    def _received(self, incoming: Incoming) -> Receipt:
+        """Turn the client's message into the shell's and ask the shell to take it."""
+        receiver = self.receiver
+        if receiver is None:
+            return Receipt(False, "this session is not taking messages yet")
+        sender = incoming.sender
+        return receiver(
+            Relayed(
+                sender_id=sender.session_id,
+                sender=sender.handle,
+                text=incoming.text,
+                via=incoming.via,
+                hops=incoming.hops,
+                direct=incoming.direct,
+                mode=incoming.mode,
+                group=incoming.group,
+                images=incoming.images,
+            )
+        )
+
+    def _roster_changed(self, roster: tuple[RosterEntry, ...]) -> None:
+        if self.on_change is not None:
+            self.on_change()
+
+    def _conflicted(self, message: str | None) -> None:
+        if self.on_conflict is not None:
+            self.on_conflict(message)
+
+    def _troubled(self, message: str | None) -> None:
+        if self.on_problem is not None:
+            self.on_problem(message)

zettcode_messaging-0.4.1/src/zettcode/messaging/plugin.py

@@ -0,0 +1,46 @@
+"""The plugin that hands the agent the tools for talking to the other sessions open on this machine."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zettcode.engine.delivery import DELIVERY, Delivery
+from zettcode.engine.plugins.plugin import Plugin
+from zettcode.engine.plugins.services import MESSENGER
+
+from .inbox import INBOX, Inbox
+from .messenger import Messenger
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zett_agent.extensions.base import AgentExtension
+
+    from zettcode.engine.plugins.context import PluginContext
+    from zettcode.engine.plugins.state import AgentBuild
+
+
+class Messaging(Plugin):
+    """The tools that talk to the other sessions open on this machine."""
+
+    name = "messaging"
+    description = "The session messaging tools"
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Provide the inbox, and register the tools when the runtime gave this session a line to the others.
+
+        The inbox is provided whether or not there is a messenger: an event from a trigger or a program reaches the
+        agent the same way, and a process that never joins the broker still has one.
+        """
+        delivery = ctx.find(DELIVERY, object)
+        if isinstance(delivery, Delivery):
+            ctx.inject(INBOX, Inbox(delivery))
+
+        messenger = ctx.find(MESSENGER, Messenger)
+        if messenger is None:
+            return
+
+        def build(_: AgentBuild) -> AgentExtension:
+            from .extension import SessionMessagingExtension
+
+            return SessionMessagingExtension(messenger)
+
+        ctx.agent.register_extension_factory("SessionMessagingExtension", build)

zettcode_messaging-0.4.1/src/zettcode/messaging/relay.py

@@ -0,0 +1,160 @@
+"""What arrives from another session, and what this one does about it.
+
+The broker hands one message at a time to the front end that owns the session's connection, and the answer is a
+receipt the sender's agent reads. The decision has three parts and this class owns the two the inbox cannot know:
+
+* whether the message can steer the request that runs — the front end supplies that answer, because steering a message
+  from another session goes through the framing a plain prompt does not have;
+* whether it was adopted, so a steer the run never read waits for the next turn instead of being lost;
+* what the sender is told, and what a front end draws while it waits.
+
+Everything else — the queue, the order, the per-message cap and starting the turns — is the inbox's
+(:class:`zettcode.messaging.inbox.Inbox`), so a message from another session and an event from elsewhere wait in one
+place and a front end has one starter.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from zettcode.broker.client import Receipt
+from zettcode.modes import MODE_STEER
+from zettcode.relay import Relayed
+
+from .inbox import FULL, QUEUED, STARTED, Inbox, Waiting
+
+__all__ = ["PREVIEW", "Relay"]
+
+#: Characters of a waiting message a front end shows, so a reader can tell which one it is.
+PREVIEW = 60
+
+#: Hand a message to the request in flight: the text the run will report it by, or ``None`` when it was not taken.
+Steer = Callable[[Relayed], "str | None"]
+
+#: The inbox to put messages in; ``None`` in a process whose messaging part did not load.
+InboxOf = Callable[[], "Inbox | None"]
+
+
+@dataclass(frozen=True, slots=True)
+class _Steered:
+    """A message handed to the running request, and the text that run will report it by."""
+
+    key: str
+    relayed: Relayed
+
+
+class Relay:
+    """The receipt a message from another session gets, and the record of what the running request took.
+
+    Args:
+        busy: Whether a request is running here.
+        steer: Hands one message to that request; the text it reports the message by, or ``None`` when it refused.
+        inbox: The runtime's inbox, read when a message is delivered (a front end may build its client lazily).
+        start: Runs one message as a turn now; only used while the front end says nothing runs.
+        on_waiting: Told about each message that starts waiting, so a front end can draw it.
+    """
+
+    def __init__(
+        self,
+        *,
+        busy: Callable[[], bool],
+        steer: Steer,
+        inbox: InboxOf,
+        start: Callable[[Relayed], None] = lambda relayed: None,
+        on_waiting: Callable[[Relayed], None] = lambda relayed: None,
+    ) -> None:
+        self._busy = busy
+        self._steer = steer
+        self._inbox_of = inbox
+        self._start = start
+        self._on_waiting = on_waiting
+        self._steered: list[_Steered] = []
+
+    @property
+    def waiting(self) -> tuple[Relayed, ...]:
+        """Return the messages from other sessions waiting for the request in flight, oldest first."""
+        inbox = self._inbox_of()
+        if inbox is None:
+            return ()
+        return tuple(item.payload for item in inbox.waiting if isinstance(item.payload, Relayed))
+
+    @property
+    def steered(self) -> tuple[tuple[str, Relayed], ...]:
+        """Return the messages handed to the request in flight, each with the text it will report it by."""
+        return tuple((item.key, item.relayed) for item in self._steered)
+
+    def receive(self, relayed: Relayed) -> Receipt:
+        """Take one message another session sent: start a turn, steer the running one, or hold it.
+
+        Called on the loop with the sender waiting for the answer; it must not block.
+        """
+        inbox = self._inbox_of()
+        if inbox is None and not self._busy():
+            # No queue to hand it to, and nothing running: the front end starts it, the way it starts a prompt.
+            self._start(relayed)
+            return Receipt(True, disposition="started")
+        if inbox is None:
+            return Receipt(False, "this session has no inbox: the messaging plugin did not load")
+        if self._busy() and relayed.mode == MODE_STEER:
+            key = self._steer(relayed)
+            if key is not None:
+                self._steered.append(_Steered(key, relayed))
+                return Receipt(True, disposition="steered")
+        outcome = self._queue(inbox, relayed)
+        if outcome == FULL:
+            return Receipt(
+                False,
+                f"this session already has {len(inbox.waiting)} messages waiting; try again when it is less busy",
+                busy=True,
+            )
+        if outcome == QUEUED:
+            self._on_waiting(relayed)
+        return Receipt(True, disposition="started" if outcome == STARTED else "queued")
+
+    def hold(self, key: str, relayed: Relayed) -> None:
+        """Record a message handed to the request in flight, for a front end that steered it itself."""
+        self._steered.append(_Steered(key, relayed))
+
+    def adopted(self, text: str) -> Relayed | None:
+        """Take the message the running request just adopted, so a front end can draw it as one."""
+        for index, item in enumerate(self._steered):
+            if item.key == text:
+                del self._steered[index]
+                return item.relayed
+        return None
+
+    def settle(self) -> tuple[Relayed, ...]:
+        """Put back what the run never adopted, after it ended, and return them in the order handed over.
+
+        A message a run adopted is not here — it left when the run reported it — so nothing the model has read is run
+        again. They go back into the inbox in the order they were handed over, and the next turn answers them.
+        """
+        if not self._steered:
+            return ()
+        inbox = self._inbox_of()
+        waiting = [item.relayed for item in self._steered]
+        self._steered.clear()
+        if inbox is not None:
+            # Already accepted, so the cap does not apply: only a new sender is refused when the queue is full.
+            inbox.requeue([Waiting(relayed.text, None, "session", relayed) for relayed in waiting])
+        for relayed in waiting:
+            self._on_waiting(relayed)
+        return tuple(waiting)
+
+    def start_next(self) -> bool:
+        """Ask the inbox to start the next waiting turn, and say whether it did.
+
+        The front end's own chain calls this after a turn ends, as a second chance for the runtime's wake-up, which
+        arrives before the front end is idle.
+        """
+        inbox = self._inbox_of()
+        if inbox is None:
+            return False
+        before = len(inbox.waiting)
+        inbox.drain()
+        return len(inbox.waiting) < before
+
+    def _queue(self, inbox: Inbox, relayed: Relayed) -> str:
+        """Put one message in the inbox as a follow-up, whatever the sender asked for."""
+        return inbox.deliver(relayed.text, mode="followup", payload=relayed, origin="session")