zettcode 0.3.2__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode
-Version: 0.3.2
+Version: 0.3.3
 Summary: A focused terminal coding agent powered by zett-agent
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
@@ -35,7 +35,7 @@ Requires-Dist: truststore<1,>=0.10
 Requires-Dist: uvicorn<1,>=0.35
 Requires-Dist: wcwidth<1,>=0.2
 Requires-Dist: websockets<17,>=15
-Requires-Dist: zett-agent<0.3,>=0.2.4
+Requires-Dist: zett-agent<0.3,>=0.2.6
 Provides-Extra: all
 Requires-Dist: zettcode-monitor<0.3,>=0.2; extra == 'all'
 Requires-Dist: zettcode-recap<0.2,>=0.1; extra == 'all'

{zettcode-0.3.2 → zettcode-0.3.3}/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.4,<0.3",
+  "zett-agent>=0.2.6,<0.3",
 ]
 
 [project.optional-dependencies]

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

{zettcode-0.3.2 → zettcode-0.3.3}/src/zettcode/broker/cli.py

@@ -22,6 +22,8 @@ from ..filelock import is_held
 from . import process
 from .files import MODULE, Note, broker_dir, lock_path, log_path, read_note, remove_note
 from .finder import spawn_broker
+from .protocol import PROTOCOL_VERSION
+from .reload import outdated
 
 EXIT_OK = 0
 EXIT_FAILED = 1
@@ -65,8 +67,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "action",
-        choices=("start", "stop", "restart"),
-        help="start a broker if there is none, stop the one there is, or do both",
+        choices=("start", "stop", "restart", "reload"),
+        help=(
+            "start a broker if there is none, stop the one there is, or do both; reload restarts it only when it is "
+            "older than this version and no background agent is on it (zettcode runs this by itself after an upgrade)"
+        ),
     )
     parser.add_argument(
         "-y",
@@ -88,10 +93,44 @@ def broker_program(argv: list[str] | None = None, companions: Companions | None
     directory = broker_dir()
     if args.action == "restart":
         return restart(directory, companions, assume_yes=args.yes)
+    if args.action == "reload":
+        return reload(directory, companions)
     action = {"start": start, "stop": stop}[args.action]
     return action(directory)
 
 
+def reload(directory: Path, companions: Companions | None = None) -> int:
+    """Replace the running broker when it is older than this version, and say nothing when there is nothing to do.
+
+    This is what runs behind every start of ``zettcode`` after an upgrade (:mod:`.reload`), so it never asks and never
+    stops what it should not: a broker with background agents on it is left as it is, with a line that says how to
+    restart it knowingly, because stopping them is something a person agrees to (``restart`` asks). A broker that is
+    current, newer, or not running is not touched. The status is 0 unless a replacement was tried and failed.
+    """
+    note = outdated(directory)
+    if note is None:
+        return EXIT_OK
+    if companions is not None and (on_it := companions.listing()):
+        count = len(on_it)
+        print(
+            f"the broker (pid {note.pid}) speaks an older protocol, but {count} background "
+            f"agent{'s are' if count != 1 else ' is'} running on it, so it was left alone: "
+            "run `zettcode broker restart` when that is fine"
+        )
+        return EXIT_OK
+    # `stop` compares the note itself, in the same step that ends the broker, so what it ends is the broker that was
+    # found and never one another start of zettcode has just put in its place.
+    if stop(directory, expect=note.pid) != EXIT_OK:
+        return EXIT_FAILED
+    if running(directory):
+        # `stop` left a broker that is not the one that was found: another start replaced it first, and it is theirs.
+        return EXIT_OK
+    status = start(directory)
+    if status == EXIT_OK:
+        print(f"replaced broker {note.pid} (protocol {note.version}) with one that speaks {PROTOCOL_VERSION}")
+    return status
+
+
 def running(directory: Path) -> bool:
     """Return whether a broker holds its lock in ``directory``, which is the only reliable sign that one is there."""
     return is_held(lock_path(directory))
@@ -118,7 +157,7 @@ def start(directory: Path) -> int:
     return EXIT_OK
 
 
-def stop(directory: Path) -> int:
+def stop(directory: Path, expect: int | None = None) -> int:
     """Stop the broker that is running, and say what happened.
 
     A note whose broker has gone is removed rather than reported: it is what the next session would read, and a
@@ -127,8 +166,14 @@ def stop(directory: Path) -> int:
     An explicit ``stop`` does not compare the broker's protocol version: that rule (never end a newer broker) is for
     a session replacing one automatically, so two versions do not end each other's in turn; a person who asks for
     this wants it stopped, whatever it says it speaks.
+
+    With ``expect``, only the broker with that process id is ended: the note is read once, here, and a broker it does
+    not name (another start of zettcode replaced the one that was meant) is left running. That is a compare and a stop
+    in one step, which a check made before calling this cannot be.
     """
     note = read_note(directory)
+    if expect is not None and (note is None or note.pid != expect):
+        return EXIT_OK
     if not running(directory):
         if note is not None:
             remove_note(directory, note.token)

{zettcode-0.3.2 → zettcode-0.3.3}/src/zettcode/broker/client.py

@@ -25,7 +25,7 @@ import itertools
 import json
 import time
 from collections import deque
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from pathlib import Path
 from typing import Any
 
@@ -38,9 +38,11 @@ from .protocol import (
     VIA_AGENT,
     VIA_USER,
     VIAS,
+    ImageData,
     Limits,
     PeerInfo,
     Refused,
+    parse_images,
     roster_from_wire,
 )
 from .text import clean_text
@@ -346,18 +348,28 @@ class BrokerClient:
 
     # -- sending ----------------------------------------------------------------------------------
     async def send(
-        self, to: str, text: str, *, hops: int = 0, via: str = VIA_AGENT, direct: bool = False, mode: str = MODE_STEER
+        self,
+        to: str,
+        text: str,
+        *,
+        hops: int = 0,
+        via: str = VIA_AGENT,
+        direct: bool = False,
+        mode: str = MODE_STEER,
+        images: Sequence[ImageData] = (),
     ) -> Delivered:
         """Send a message to another session and return once it has taken it.
 
         Args:
             to: The session's handle or id.
-            text: What to say.
+            text: What to say; it may be empty when ``images`` is not.
             hops: How many sessions it has passed through already.
             via: How it came: the reader, the agent, or an external program.
             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 it. Only a ``direct`` message from a reader may carry them, and the broker
+                refuses them for any other.
 
         Raises:
             SendError: There is no broker, or the broker or the recipient refused, or nobody answered in time, or
@@ -365,10 +377,12 @@ class BrokerClient:
         """
         if mode not in MODES:
             raise SendError("invalid", "mode is 'steer' or 'followup'")
-        cleaned = self._checked(text)
-        body = {"to": to, "text": cleaned, "via": via, "hops": hops, "mode": mode}
+        cleaned = self._checked(text, silent=bool(images))
+        body: dict[str, Any] = {"to": to, "text": cleaned, "via": via, "hops": hops, "mode": mode}
         if direct:
             body["direct"] = True
+        if images:
+            body["images"] = [picture.to_wire() for picture in images]
         return self._delivered(await self._request("POST", "/messages", json=body, send=True))
 
     async def send_group(
@@ -398,9 +412,9 @@ class BrokerClient:
         )
         return GroupDelivered(name if isinstance(name, str) else group, tuple(delivered), failed)
 
-    def _checked(self, text: str) -> str:
+    def _checked(self, text: str, *, silent: bool = False) -> str:
         cleaned = clean_text(text)
-        if not cleaned.strip():
+        if not cleaned.strip() and not silent:
             raise SendError("empty", "a message needs some text")
         if len(cleaned) > self.limits.max_text:
             raise SendError("too_long", f"a message is limited to {self.limits.max_text} characters")
@@ -679,6 +693,10 @@ class BrokerClient:
             mode = MODE_STEER  # a peer that does not say: the protocol's default
         elif mode not in MODES:
             mode = MODE_FOLLOWUP  # one this version does not know: the safe half, not the disruptive one
+        try:
+            pictures = parse_images(line.get("images")) if line.get("direct") is True and via == VIA_USER else ()
+        except Refused:
+            return _ack(Receipt(False, "the message's pictures were malformed"))
         incoming = Incoming(
             sender,
             clean_text(text),
@@ -687,6 +705,7 @@ class BrokerClient:
             line.get("direct") is True and via == VIA_USER,
             mode,
             line["group"] if isinstance(line.get("group"), str) else "",
+            pictures,
         )
         try:
             return _ack(self.on_message(incoming))

{zettcode-0.3.2 → zettcode-0.3.3}/src/zettcode/broker/finder.py

@@ -30,7 +30,7 @@ from .. import logging_setup
 from ..filelock import is_held
 from . import process
 from .files import MODULE, Note, broker_dir, ensure_directory, lock_path, log_path, read_note
-from .protocol import MAX_BODY, PROTOCOL_VERSION
+from .protocol import MAX_MESSAGE_BODY, PROTOCOL_VERSION
 
 #: A broker is started at most this often, so one that dies at once is not restarted in a loop.
 SPAWN_INTERVAL = 3.0
@@ -152,7 +152,7 @@ class Finder:
                 additional_headers={"Authorization": f"Bearer {note.token}"},
                 proxy=None,  # never through a proxy named in the environment: the broker is on this machine
                 compression=None,
-                max_size=MAX_BODY,
+                max_size=MAX_MESSAGE_BODY,
                 open_timeout=self.connect_timeout,
             )
         except InvalidStatus as refused:

{zettcode-0.3.2 → zettcode-0.3.3}/src/zettcode/broker/hub.py

@@ -39,20 +39,27 @@ from .protocol import (
     STREAM_TYPES,
     VIA_EXTERNAL,
     VIA_USER,
+    ImageData,
     Limits,
     PeerInfo,
     Refused,
     SessionUpdate,
     group_name,
+    parse_images,
     parse_send,
 )
 from .roster import Entry, Roster
-from .store import KIND_GROUP, KIND_SESSION, Store
+from .store import KIND_GROUP, KIND_SESSION, MAX_WINDOW, Store
 from .text import clean_text, clean_title, slug
 
 #: Messages waiting for one session to say it took them. More are told the session is busy.
 MAX_WAITING = 32
 
+#: The pictures, as base64, that one session may have waiting for it at once: in messages it has not answered, and in
+#: lines it has not read. A message may carry about 11 MiB of them, and a session that has stopped answering would
+#: otherwise hold hundreds of those in the broker.
+MAX_WAITING_PICTURES = 96 << 20
+
 #: Lines queued for one session to read. A session that is this far behind has stopped reading and is dropped.
 MAX_QUEUED = 256
 
@@ -103,6 +110,11 @@ class Session:
         #: Whether this connection asked to be told of every message that passes (the gateway's graph does).
         self.observing = False
         self._waiting: dict[int, asyncio.Future[dict[str, Any]]] = {}
+        #: The size, as base64, of the pictures in the messages in ``_waiting``.
+        self._weight = 0
+        #: The size, as base64, of the pictures in the lines still in ``outbox``, which a message whose ack timed out
+        #: leaves behind: a socket that never drains must not be able to hold more than the budget.
+        self._queued = 0
         self._deliveries = itertools.count(1)
 
     def push(self, line: dict[str, Any]) -> None:
@@ -113,6 +125,14 @@ class Session:
             if not self._dropped:
                 self._dropped = True
                 self.close(STOPPED_READING)
+        else:
+            self._queued += _picture_weight(line)
+
+    async def next_line(self) -> dict[str, Any]:
+        """Take the next queued line, for the writer to send: its pictures stop counting against this session's budget."""
+        line = await self.outbox.get()
+        self._queued -= _picture_weight(line)
+        return line
 
     def push_lossy(self, line: dict[str, Any]) -> None:
         """Queue a line that may be lost: when this session is half a queue behind it is skipped, not dropped for it.
@@ -138,14 +158,19 @@ class Session:
         """
         if self.waiting >= MAX_WAITING:
             raise Refused("busy", "that session has too many messages waiting")
+        weight = sum(len(picture.get("data", "")) for picture in message.get("images", ()))
+        if weight and self._weight + self._queued + weight > MAX_WAITING_PICTURES:
+            raise Refused("busy", "that session has too many pictures waiting")
         number = next(self._deliveries)
         ack: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
         self._waiting[number] = ack
+        self._weight += weight
         try:
             self.push({"op": "deliver", "id": number, **message})
             return await asyncio.wait_for(ack, timeout)
         finally:
             self._waiting.pop(number, None)
+            self._weight -= weight
 
     def acked(self, line: dict[str, Any]) -> None:
         """Take an ack; one for something that was never asked, or already answered, is ignored."""
@@ -307,7 +332,11 @@ class Hub:
         if sender.external:
             body = {**body, "via": VIA_EXTERNAL}
         group = body.get("group")
+        # Looked at, not yet decoded: a message that may not carry pictures is turned away before they cost anything.
+        offered = body.get("images")
         if group is not None:
+            if offered:
+                raise Refused("invalid", "pictures go to one session, not to a group")
             if body.get("to") not in (None, ""):
                 raise Refused("invalid", "name a session in 'to' or a group in 'group', not both")
             # The group's name stands where a session's would while the text, the hops and the mode are checked.
@@ -315,7 +344,7 @@ class Hub:
             if via == VIA_EXTERNAL and not sender.external:
                 raise Refused("invalid", "via is 'user' or 'agent'")
             return await self._send_group(sender, group_name(group), text, via, hops, mode)
-        to, text, via, hops, mode = parse_send(body, self.limits)
+        to, text, via, hops, mode = parse_send(body, self.limits, may_be_silent=bool(offered))
         if via == VIA_EXTERNAL and not sender.external:
             raise Refused("invalid", "via is 'user' or 'agent'")
         target = self.roster.resolve(to, asker=sender.connection)
@@ -327,13 +356,24 @@ class Hub:
         # that said it can; for any other the flag is dropped and the message is delivered the ordinary way.
         if body.get("direct") is True and via == VIA_USER and not sender.external and target.direct:
             message["direct"] = True
+        pictures: tuple[ImageData, ...] = ()
+        if offered:
+            # Only a session that runs the message as its reader's own prompt has anywhere to put a picture: for any
+            # other the pictures would be dropped on the way in, and the sender told it went through.
+            if message.get("direct") is not True:
+                raise Refused(
+                    "invalid",
+                    f"@{target.handle} does not take pictures: it does not run a chat's text as its own prompt",
+                )
+            pictures = parse_images(offered)
+            message["images"] = [picture.to_wire() for picture in pictures]
         ack = await self._hand_over(recipient, message, target.handle)
         stored = self._remember(
             sender,
             KIND_SESSION,
             (target.session_id, target.handle, target.title),
             [target.session_id],
-            text,
+            _with_pictures(text, len(pictures)),
             via,
             hops + 1,
             mode,
@@ -624,11 +664,19 @@ class Hub:
     def timeline(self, since: float, until: float, limit: int) -> dict[str, Any]:
         """Return the messages of a stretch of the past, oldest first, for a front end to replay on screen.
 
-        Nothing is sent again: this is only what was stored.
+        Nothing is sent again: this is only what was stored. When more than ``limit`` messages fall in the stretch the
+        newest are returned and ``truncated`` says so, so that a replay can say it is missing the start of the stretch
+        rather than draw a flow that is quietly incomplete.
         """
+        # One less than the most a read may return, so that the extra row asked for below is always really read: at the
+        # cap itself the count could never exceed the limit, and a stretch of fifty thousand would be called complete.
+        limit = max(1, min(limit, MAX_WINDOW - 1))
+        found = self.store.window(since, until, limit=limit + 1)
+        truncated = len(found) > limit
         span = self.store.span()
         return {
-            "messages": self.store.window(since, until, limit=limit),
+            "messages": found[-limit:] if truncated else found,
+            "truncated": truncated,
             "span": list(span) if span else None,
             "now": time.time(),
         }
@@ -715,6 +763,22 @@ class Hub:
         session.push({"op": "roster", "sessions": [entry.to_wire() for entry in self.roster.snapshot()]})
 
 
+def _picture_weight(line: Mapping[str, Any]) -> int:
+    """Return the size, as base64, of the pictures a line carries: a ``deliver`` is the only line that has any."""
+    images = line.get("images")
+    if not isinstance(images, list):
+        return 0
+    return sum(len(item.get("data", "")) for item in images if isinstance(item, dict))
+
+
+def _with_pictures(text: str, count: int) -> str:
+    """Return what the history keeps of a message: its words, and how many pictures went with it, never the pictures."""
+    if not count:
+        return text
+    note = f"[{count} picture{'s' if count != 1 else ''}]"
+    return f"{text}\n{note}" if text.strip() else note
+
+
 def _count(raw: object, default: int) -> int:
     """Read a count from a query string; one that is not a number is the default."""
     try:

{zettcode-0.3.2 → zettcode-0.3.3}/src/zettcode/broker/models.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from ..modes import MODE_STEER
-from .protocol import KIND_ZETTCODE, PeerInfo
+from .protocol import KIND_ZETTCODE, ImageData, PeerInfo
 
 #: Another word for a registered session, as the rest of the application knows it.
 RosterEntry = PeerInfo
@@ -38,6 +38,7 @@ class Incoming:
         mode: What a busy recipient should do with it: ``"steer"`` (the default) hands it to the request that is
             running, and ``"followup"`` waits until that request ends. An idle recipient starts a turn either way.
         group: The group chat it was written in (without the ``#``), or an empty string for a one-to-one message.
+        images: The pictures it carries, already checked: only a ``direct`` message has any.
     """
 
     sender: PeerInfo
@@ -47,6 +48,7 @@ class Incoming:
     direct: bool = False
     mode: str = MODE_STEER
     group: str = ""
+    images: tuple[ImageData, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)

{zettcode-0.3.2 → zettcode-0.3.3}/src/zettcode/broker/protocol.py

@@ -16,7 +16,8 @@ HTTP, for anyone who holds the token — a session, a script, a hook, ``curl``::
                        the owner's token alone: ?a=&b= or ?group=)  ->  {"messages": [...]}
     GET  /graph        ->  {"sessions", "groups", "edges", "recent"}   (token only; for the gateway's graph)
     GET  /older        ?before=<message id>&limit=  ->  {"messages", "more"}   the stored messages before one
-    GET  /timeline     ?since=&until=&limit=  ->  {"messages", "span", "now"}   stored messages, to replay on screen
+    GET  /timeline     ?since=&until=&limit=  ->  {"messages", "truncated", "span", "now"}   stored messages, to replay on
+                       screen (at most MAX_WINDOW; "truncated" says the stretch held more and its start is missing)
 
 A failure is an HTTP status and ``{"error": {"reason", "message"}}``; the reason is what a program acts on. A
 message's ``mode`` says what a busy recipient should do with it: ``steer`` (the default) hands it to the request
@@ -32,7 +33,7 @@ A *session* — ZettCode's, or any program that wants to be listed and reached
     {"op": "traffic", "kind": "message"|"graph", "message"?}         to an observer: what passed, what changed
     {"op": "done", "n": 1, "handle": ...}                            the answer to a session or leave
     {"op": "refused", "n": 1, "error": {"reason", "message"}}        ... or its refusal
-    {"op": "deliver", "id": 9, "from": {...}, "text", "hops", "via", "mode"} a message; answer with an ack
+    {"op": "deliver", "id": 9, "from": {...}, "text", "hops", "via", "mode", "images"?} a message; answer with an ack
 
 and the session says::
 
@@ -68,6 +69,7 @@ characters the composer can type, a chain of messages that keep triggering one a
 
 from __future__ import annotations
 
+import base64
 import re
 from collections.abc import Mapping
 from dataclasses import dataclass
@@ -76,15 +78,24 @@ from typing import Any
 from ..modes import MODE_STEER, MODES
 from .text import clean_text, clean_title
 
-#: Bumped whenever this protocol changes meaning. 8: group chats (``group`` on a send, the ``groups`` line, ``/groups``),
+#: Bumped whenever this protocol changes meaning. 9: a one-to-one message may carry pictures (``images`` on a send and
+#: on a ``deliver``, with a longer line for the ``deliver``); 8: group chats (``group`` on a send, the ``groups`` line,
+#: ``/groups``),
 #: the persistent ``/history``, and observers (``observe``, the ``traffic`` line); 7: a message says whether a busy recipient should steer its running
 #: request with it or wait behind that request (``mode``, default steer); 6 was the HTTP server and its WebSocket per
 #: session, 5 lines of JSON on a TCP socket.
-PROTOCOL_VERSION = 8
+PROTOCOL_VERSION = 9
 
 #: The longest message, in characters. Longer than anyone types, shorter than a paste of a file.
 MAX_TEXT = 32_000
 
+#: The pictures a one-to-one chat message may carry: how many, how large each is once decoded, and how large they are
+#: together. The broker keeps none of them: it hands them over and writes down only how many there were.
+IMAGE_TYPES = ("image/png", "image/jpeg", "image/gif", "image/webp")
+MAX_IMAGES = 4
+MAX_IMAGE_BYTES = 4 << 20
+MAX_IMAGES_BYTES = 8 << 20
+
 #: The longest title the roster keeps; a longer one is cut.
 MAX_TITLE = 120
 
@@ -95,6 +106,11 @@ MAX_WORKSPACE = 512
 #: character escaped) and a roster of a few hundred sessions both fit. A longer one is refused or ends the connection.
 MAX_BODY = 1 << 20
 
+#: The longest ``POST /messages`` body, and the longest line a session reads from the broker: :data:`MAX_BODY` for the
+#: words, plus the pictures a message may carry as base64 (a third larger than they are). Everything else a session sends
+#: stays within :data:`MAX_BODY`.
+MAX_MESSAGE_BODY = MAX_BODY + (MAX_IMAGES_BYTES + 2) // 3 * 4
+
 #: How many sessions a message may pass through. A reader who typed it is hop zero; each session whose agent
 #: forwards it adds one. Two agents that answer each other would otherwise spend tokens for ever, so the broker
 #: refuses the message that would be hop :data:`MAX_HOPS` + 1.
@@ -177,6 +193,75 @@ class Refused(Exception):
         return cls("invalid", "the other end refused without saying why")
 
 
+@dataclass(frozen=True, slots=True)
+class ImageData:
+    """One picture a message carries: its media type and the encoded file (not decoded pixels)."""
+
+    media_type: str
+    data: bytes
+
+    def to_wire(self) -> dict[str, str]:
+        """Return the picture as a line carries it: the media type and the file in base64."""
+        return {"media_type": self.media_type, "data": base64.b64encode(self.data).decode("ascii")}
+
+
+def sniff_image(data: bytes) -> str | None:
+    """Return the media type a file's first bytes say it is, or ``None`` when it is not a picture a model takes."""
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if data.startswith((b"GIF87a", b"GIF89a")):
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def parse_images(raw: object) -> tuple[ImageData, ...]:
+    """Read the pictures a send carries, refusing what is not one.
+
+    A picture is ``{"media_type", "data"}`` with the file in base64. What it says it is must be what its first bytes say,
+    so a program cannot hand a model something else under an image's name, and each picture and all of them together
+    are bounded.
+
+    Raises:
+        Refused: ``invalid`` for a malformed or mislabelled picture, ``too_long`` for too many or too large.
+    """
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise Refused("invalid", "images is a list")
+    if len(raw) > MAX_IMAGES:
+        raise Refused("too_long", f"a message may carry at most {MAX_IMAGES} pictures")
+    pictures: list[ImageData] = []
+    total = 0
+    for item in raw:
+        if not isinstance(item, Mapping) or not isinstance(item.get("data"), str):
+            raise Refused("invalid", "a picture is {media_type, data}")
+        kind = item.get("media_type")
+        if kind not in IMAGE_TYPES:
+            raise Refused("invalid", f"a picture is one of: {', '.join(IMAGE_TYPES)}")
+        encoded: str = item["data"]
+        if len(encoded) > (MAX_IMAGE_BYTES + 2) // 3 * 4:
+            raise Refused("too_long", f"a picture is limited to {MAX_IMAGE_BYTES >> 20} MiB")
+        try:
+            data = base64.b64decode(encoded, validate=True)
+        except ValueError:
+            raise Refused("invalid", "a picture's data is not base64") from None
+        if not data:
+            raise Refused("invalid", "a picture is empty")
+        if len(data) > MAX_IMAGE_BYTES:
+            raise Refused("too_long", f"a picture is limited to {MAX_IMAGE_BYTES >> 20} MiB")
+        if sniff_image(data) != kind:
+            raise Refused("invalid", f"a picture said to be {kind} is not")
+        total += len(data)
+        if total > MAX_IMAGES_BYTES:
+            raise Refused("too_long", f"the pictures of a message are limited to {MAX_IMAGES_BYTES >> 20} MiB together")
+        pictures.append(ImageData(str(kind), data))
+    return tuple(pictures)
+
+
 def field(raw: Mapping[str, Any], name: str, kind: type, default: Any = None) -> Any:
     """Return a field of a line, or ``default`` when it is missing; a field of the wrong kind is ``invalid``."""
     value = raw.get(name, default)
@@ -319,19 +404,22 @@ class SessionUpdate:
         return cls(session_id, *_description(raw), _kind(raw), raw.get("direct") is True)
 
 
-def parse_send(raw: Mapping[str, Any], limits: Limits) -> tuple[str, str, str, int, str]:
+def parse_send(
+    raw: Mapping[str, Any], limits: Limits, *, may_be_silent: bool = False
+) -> tuple[str, str, str, int, str]:
     """Read and check a ``send``: who it is for, its cleaned text, how it came, its hops, and its mode.
 
     The text is cleaned (see :func:`~.text.clean_text`) before it is measured, so the limit is on what would be
     delivered. A message a reader typed, or one from outside, starts a chain whatever hop count it claims. The mode
-    is :data:`MODE_STEER` unless the sender asked for :data:`MODE_FOLLOWUP`.
+    is :data:`MODE_STEER` unless the sender asked for :data:`MODE_FOLLOWUP`. ``may_be_silent`` allows no words at all,
+    for a message that carries pictures.
 
     Raises:
         Refused: ``invalid`` for a field of the wrong kind or a mode the recipient does not know, ``empty`` for
             nothing to say, ``too_long`` past the limit, ``loop`` when the message would pass the hop limit.
     """
     to = field(raw, "to", str)
-    text = clean_text(field(raw, "text", str))
+    text = clean_text(field(raw, "text", str, "" if may_be_silent else None))
     via = field(raw, "via", str, VIA_AGENT)
     hops = field(raw, "hops", int, 0)
     mode = field(raw, "mode", str, MODE_STEER)
@@ -341,7 +429,7 @@ def parse_send(raw: Mapping[str, Any], limits: Limits) -> tuple[str, str, str, i
         raise Refused("invalid", "mode is 'steer' or 'followup'")
     if hops < 0:
         raise Refused("invalid", "hops is a count")
-    if not text.strip():
+    if not text.strip() and not may_be_silent:
         raise Refused("empty", "a message needs some text")
     if len(text) > limits.max_text:
         raise Refused("too_long", f"a message is limited to {limits.max_text} characters")