zettcode-gateway 0.3.4__py3-none-any.whl

zettcode/gateway/backend.py

@@ -0,0 +1,368 @@
+"""What the gateway needs from the agent, as an interface, and the implementation that gets it from the SDK.
+
+The gateway's logic (:mod:`.service`) is written against :class:`Backend`, so it can be tested with a backend that
+answers from memory. :class:`SdkBackend` is the real one and the only module of the gateway that touches
+``zettcode.sdk.Client``: it is a session of its own, registered with the broker like a terminal's, which has a person
+at it and runs no model.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+from zettcode.modes import MODE_FOLLOWUP
+from zettcode.sdk import daemons as sdk_daemons
+from zettcode.sdk.client import Client
+from zettcode.sdk.errors import ConfigurationError, SendError, SessionLockedError, SessionNotFoundError, ZettCodeError
+from zettcode.sdk.models import add_model, list_models, remove_model, update_model
+from zettcode.sdk.types import (
+    DaemonInfo,
+    Delivered,
+    Image,
+    IncomingMessage,
+    Message,
+    ModelInfo,
+    Peer,
+    Receipt,
+    SendLimits,
+    StreamEvent,
+)
+
+#: What the gateway's own session is called, so the sessions it writes to can tell who is speaking.
+TITLE = "Web gateway"
+
+#: The file in the gateway's folder that remembers the id of its session, so a restart is the same session to the
+#: daemons that were told where to answer.
+HOST_FILE = "host.json"
+
+
+class GatewayStartError(ZettCodeError):
+    """The gateway could not become a session: no model is configured, or another gateway is running."""
+
+
+class Backend(ABC):
+    """The agent as the gateway sees it: who is there, what they said, and how to speak to them."""
+
+    @property
+    @abstractmethod
+    def gateway_id(self) -> str:
+        """Return the id the gateway is registered under: what a daemon replies to."""
+
+    @property
+    @abstractmethod
+    def handle(self) -> str:
+        """Return the name the others call the gateway by, or an empty string before it is registered."""
+
+    @property
+    @abstractmethod
+    def reachable(self) -> bool:
+        """Return whether the broker is connected: without it nobody can be written to."""
+
+    @property
+    @abstractmethod
+    def limits(self) -> SendLimits:
+        """Return what the broker accepts from a sender."""
+
+    @abstractmethod
+    async def start(self, on_message: Callable[[IncomingMessage], Receipt], on_change: Callable[[], None]) -> None:
+        """Become reachable. ``on_message`` is told of each message another session sends; ``on_change`` of any
+        change in who is there or whether the broker is."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Leave the broker and release the session. Safe to call twice."""
+
+    @abstractmethod
+    def peers(self) -> tuple[Peer, ...]:
+        """Return the other registered sessions, from memory."""
+
+    def watch(self, session_id: str) -> None:  # noqa: B027 - a backend with no streams watches nothing
+        """Ask to be told what a session's turns say as they happen. Asking twice is the same as once."""
+
+    def unwatch(self, session_id: str) -> None:  # noqa: B027
+        """Stop being told what a session's turns say."""
+
+    def on_stream(self, callback: Callable[[StreamEvent], None]) -> None:  # noqa: B027
+        """Call ``callback`` on the event loop with every event of a watched session's turn."""
+
+    def observe(self, callback: Callable[[dict[str, Any]], None] | None) -> None:  # noqa: B027
+        """Call ``callback`` with every message that passes through the broker, and when who is here changes."""
+
+    async def graph(self) -> dict[str, Any]:
+        """Return the broker's picture of who talks to whom (see ``Client.traffic_graph``); empty without a broker."""
+        return {"sessions": [], "groups": [], "edges": [], "recent": []}
+
+    async def older(self, before: int, limit: int, group: str = "") -> dict[str, Any]:
+        """Return the stored messages before id ``before`` (see ``Client.traffic_older``); a group's own with ``group``."""
+        return {"messages": [], "more": False}
+
+    async def send_group(self, group: str, text: str) -> list[Delivered]:
+        """Write to a group chat as the person at the gateway and return who took it (see ``Client.send_group``)."""
+        raise SendError("offline", "not connected to the session broker")
+
+    async def join_group(self, group: str) -> None:
+        """Make the gateway a member of a group so that it can write to it (see ``Client.join_group``)."""
+        raise SendError("offline", "not connected to the session broker")
+
+    async def timeline(self, since: float, until: float, limit: int) -> dict[str, Any]:
+        """Return the stored messages of a stretch of the past (see ``Client.traffic_timeline``)."""
+        return {"messages": [], "truncated": False, "span": None, "now": until}
+
+    @abstractmethod
+    async def send(self, to: str, text: str, *, direct: bool = False, images: Sequence[Image] = ()) -> Delivered:
+        """Send a message as the person at the gateway and return once the session has taken it.
+
+        A backend sends it as the person at the gateway and never steers a turn the page does not show: a message
+        waits for the session's current request to end (see the implementation for the mode it uses).
+
+        With ``direct``, a session that can (``Peer.direct``) runs it as its reader's own prompt and sends its final
+        answer back here; for any other the flag is ignored. Only a ``direct`` message may carry ``images``.
+
+        Raises:
+            zettcode.sdk.errors.SendError: Nobody was reached, and why.
+        """
+
+    def locked(self, session_id: str, workspace: str) -> bool:  # noqa: ARG002
+        """Return whether another process has this stored session open (its lock is held)."""
+        return False
+
+    @abstractmethod
+    async def history(self, session_id: str, workspace: str) -> list[Message]:
+        """Return a stored conversation of any session, or raise ``SessionNotFoundError``."""
+
+    @abstractmethod
+    def stamp(self, session_id: str, workspace: str) -> tuple[int, int] | None:
+        """Return a value that changes when the stored conversation does, or ``None`` when there is none."""
+
+    @abstractmethod
+    def models(self) -> list[ModelInfo]:
+        """Return the models a daemon can run on, the first being the default."""
+
+    @abstractmethod
+    def add_model(self, entry: dict[str, object]) -> list[ModelInfo]:
+        """Write a model into the configuration file and return every model it now lists (``ValueError`` if unusable)."""
+
+    @abstractmethod
+    def update_model(self, name: str, changes: dict[str, object]) -> list[ModelInfo]:
+        """Change one model; a key whose value is ``None`` is removed, and the token is kept unless given."""
+
+    @abstractmethod
+    def remove_model(self, name: str) -> list[ModelInfo]:
+        """Remove one model; the last cannot go (``ValueError``)."""
+
+    @abstractmethod
+    def daemons(self) -> list[DaemonInfo]:
+        """Return every daemon on this machine, newest first."""
+
+    @abstractmethod
+    async def spawn(
+        self,
+        workspace: Path,
+        *,
+        model: str | None,
+        effort: str | None,
+        resume: str | None,
+        name: str | None,
+        permission: str,
+    ) -> DaemonInfo:
+        """Start a daemon and return it once it can be messaged."""
+
+    @abstractmethod
+    async def stop(self, session_id: str, *, force: bool) -> str:
+        """Stop a daemon and keep its record, listed as offline, and say what happened."""
+
+    @abstractmethod
+    async def delete(self, session_id: str) -> str:
+        """Remove a stopped daemon for good, record and conversation, and say what happened."""
+
+    @abstractmethod
+    def log(self, session_id: str, lines: int) -> str:
+        """Return the end of a daemon's own log."""
+
+
+class SdkBackend(Backend):
+    """The backend that is a real session: an SDK client that joined the broker, and the SDK's daemon calls."""
+
+    def __init__(self, workspace: Path, directory: Path) -> None:
+        """Remember where the gateway's session works and where it keeps its id; nothing starts until :meth:`start`."""
+        self.workspace = workspace
+        self.directory = directory
+        self._client: Client | None = None
+
+    # -- the session ------------------------------------------------------------------------------
+    async def start(self, on_message: Callable[[IncomingMessage], Receipt], on_change: Callable[[], None]) -> None:
+        """Make the client, take its old id back when it has one, join the broker and watch who is there.
+
+        Raises:
+            GatewayStartError: No model is configured (the session needs one to exist, though it never calls it), or
+                another gateway holds the session.
+        """
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        client = self._build(self._remembered())
+        try:
+            if client.session.locked:
+                raise GatewayStartError("another gateway is already running for this user")
+            if client.session.title is None:
+                await client.session.rename(TITLE)
+            self._remember(client.session.id)
+            if not await client.join_sessions(on_message):
+                raise GatewayStartError("sessions are switched off in the configuration, so nothing can be reached")
+        except BaseException:
+            await client.aclose()
+            raise
+        client.watch_peers(on_change)
+        self._client = client
+
+    def _build(self, resume: str | None) -> Client:
+        """Return the client; a session that was remembered and has since gone is replaced by a new one."""
+        settings = {
+            "sessions_enabled": True,
+            "update_enabled": False,
+            "plugins_enabled": False,
+            "mcp_enabled": False,
+            "skills_enabled": False,
+            "agents_md_enabled": False,
+            "ask_user_enabled": False,
+            "subagent_enabled": False,
+            "permission": "deny",
+        }
+        try:
+            return Client(self.workspace, resume=resume, **settings)  # type: ignore[arg-type]
+        except SessionNotFoundError:
+            return Client(self.workspace, **settings)  # type: ignore[arg-type]
+        except ConfigurationError as error:
+            raise GatewayStartError(f"{error}. Add a model with `zettcode` (/config) or in the config file.") from error
+        except SessionLockedError as error:
+            raise GatewayStartError("another gateway is already running for this user") from error
+
+    def _remembered(self) -> str | None:
+        try:
+            data = json.loads((self.directory / HOST_FILE).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        session = data.get("session") if isinstance(data, dict) else None
+        return session if isinstance(session, str) and session else None
+
+    def _remember(self, session_id: str) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        temporary = self.directory / f".{HOST_FILE}.{os.getpid()}.tmp"
+        temporary.write_text(json.dumps({"session": session_id}), encoding="utf-8")
+        os.replace(temporary, self.directory / HOST_FILE)
+
+    @property
+    def client(self) -> Client:
+        """Return the client; asking before :meth:`start` is a bug of the caller's."""
+        if self._client is None:
+            raise GatewayStartError("the gateway has not started")
+        return self._client
+
+    async def close(self) -> None:
+        client, self._client = self._client, None
+        if client is not None:
+            client.watch_peers(None)
+            await client.aclose()
+
+    # -- who is there and what was said -----------------------------------------------------------
+    @property
+    def gateway_id(self) -> str:
+        return self.client.session.id
+
+    @property
+    def handle(self) -> str:
+        return self.client.handle
+
+    @property
+    def reachable(self) -> bool:
+        return self._client is not None and self._client.reachable
+
+    @property
+    def limits(self) -> SendLimits:
+        return self.client.send_limits
+
+    def peers(self) -> tuple[Peer, ...]:
+        return self.client.peers()
+
+    def watch(self, session_id: str) -> None:
+        self.client.watch(session_id)
+
+    def unwatch(self, session_id: str) -> None:
+        self.client.unwatch(session_id)
+
+    def on_stream(self, callback: Callable[[StreamEvent], None]) -> None:
+        self.client.watch_streams(callback)
+
+    def observe(self, callback: Callable[[dict[str, Any]], None] | None) -> None:
+        self.client.watch_traffic(callback)
+
+    async def graph(self) -> dict[str, Any]:
+        return await self.client.traffic_graph()
+
+    async def older(self, before: int, limit: int, group: str = "") -> dict[str, Any]:
+        return await self.client.traffic_older(before, limit, group)
+
+    async def send_group(self, group: str, text: str) -> list[Delivered]:
+        return await self.client.send_group(group, text, mode=MODE_FOLLOWUP)
+
+    async def join_group(self, group: str) -> None:
+        await self.client.join_group(group)
+
+    async def timeline(self, since: float, until: float, limit: int) -> dict[str, Any]:
+        return await self.client.traffic_timeline(since, until, limit)
+
+    async def send(self, to: str, text: str, *, direct: bool = False, images: Sequence[Image] = ()) -> Delivered:
+        # A page keeps a conversation instead of watching the session's live turn, so its message never steers one:
+        # a person typing here cannot see what they would be interrupting.
+        return await self.client.send(to, text, direct=direct, mode=MODE_FOLLOWUP, images=images)
+
+    def locked(self, session_id: str, workspace: str) -> bool:
+        return self.client.sessions.open_elsewhere(session_id, workspace=workspace or None)
+
+    async def history(self, session_id: str, workspace: str) -> list[Message]:
+        return await self.client.sessions.history_of(session_id, workspace=workspace or None, full=True)
+
+    def stamp(self, session_id: str, workspace: str) -> tuple[int, int] | None:
+        return self.client.sessions.stamp(session_id, workspace=workspace or None)
+
+    # -- daemons ----------------------------------------------------------------------------------
+    def models(self) -> list[ModelInfo]:
+        return list(list_models())
+
+    def add_model(self, entry: dict[str, object]) -> list[ModelInfo]:
+        return list(add_model(entry))
+
+    def update_model(self, name: str, changes: dict[str, object]) -> list[ModelInfo]:
+        return list(update_model(name, changes))
+
+    def remove_model(self, name: str) -> list[ModelInfo]:
+        return list(remove_model(name))
+
+    def daemons(self) -> list[DaemonInfo]:
+        return sdk_daemons.list_daemons()
+
+    async def spawn(
+        self,
+        workspace: Path,
+        *,
+        model: str | None,
+        effort: str | None,
+        resume: str | None,
+        name: str | None,
+        permission: str,
+    ) -> DaemonInfo:
+        return await sdk_daemons.spawn_daemon(
+            workspace, model=model, effort=effort, resume=resume, name=name, permission=permission
+        )
+
+    async def stop(self, session_id: str, *, force: bool) -> str:
+        return await sdk_daemons.stop_daemon(session_id, force=force, keep=True)
+
+    async def delete(self, session_id: str) -> str:
+        return await sdk_daemons.delete_daemon(session_id)
+
+    def log(self, session_id: str, lines: int) -> str:
+        return sdk_daemons.daemon_log(session_id, lines=lines)

zettcode/gateway/chat.py

@@ -0,0 +1,142 @@
+"""A stored conversation as a chat: the SDK's messages turned into the items a chat view draws.
+
+The gateway shows a session the way a messenger shows a contact, so a conversation is not a transcript of model
+turns but a list of things said (by this gateway, by the session) and a few quiet marks for what the agent did in
+between. This module is that translation and nothing else: no I/O, and nothing about HTTP, so every rule here is a
+function of the messages it is given.
+
+An item is a plain dict with a ``kind``:
+
+* ``out`` -- this gateway said it (a message the stored conversation records as relayed from the gateway's id);
+* ``from`` -- another session or program said it to this one (``sender`` and ``via`` say who);
+* ``user`` -- what the person at that session typed, when it is a session with a person at it;
+* ``in`` -- what the session's agent answered in words;
+* ``reply`` -- the agent used ``send_message`` to speak to this gateway, which is the way a daemon answers;
+* ``tool`` -- a tool the agent ran, with a short account of its arguments and how it ended;
+* ``note`` -- the summary a compaction left in place of older messages.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Iterable, Sequence
+
+from zettcode.sdk.types import Message, brief_of
+
+#: The line added after what the reader typed, asking the agent to answer with ``send_message``. A daemon answers a
+#: message only when its model chooses to, and a daemon that goes quiet cannot be told from one with nothing to say.
+REPLY_REQUEST = (
+    '[Web gateway: when you have finished, reply with send_message(to="{id}", message=...). '
+    "If there is nothing to report, say so in one line.]"
+)
+
+#: Matches the request above whatever id it carries, so the chat shows what the reader typed and not the scaffolding.
+_BEFORE, _AFTER = (re.escape(part) for part in REPLY_REQUEST.split("{id}"))
+_REPLY_REQUEST = re.compile(rf"\n\n{_BEFORE}[^\"]*{_AFTER}\Z")
+
+#: Longest tool output kept on an item; the chat shows it folded and has no use for more.
+OUTPUT_LIMIT = 1_200
+
+#: The tool an agent speaks to another session with.
+SEND_TOOL = "send_message"
+
+#: The kinds that are words said to the reader of the chat, as opposed to what the agent did.
+SPOKEN = frozenset({"in", "reply"})
+
+
+def with_reply_request(text: str, gateway_id: str) -> str:
+    """Return the text to send: what the reader typed, then the request to answer with ``send_message``."""
+    return f"{text}\n\n{REPLY_REQUEST.format(id=gateway_id)}"
+
+
+def strip_reply_request(text: str) -> str:
+    """Return what the reader typed, without the request :func:`with_reply_request` added."""
+    return _REPLY_REQUEST.sub("", text)
+
+
+def items_of(messages: Sequence[Message], gateway_id: str, *, handle: str = "") -> list[dict[str, object]]:
+    """Return the chat items for a conversation, oldest first.
+
+    Args:
+        messages: The conversation as the SDK reads it.
+        gateway_id: The id this gateway is registered under, which marks a message as its own.
+        handle: The name the others call this gateway by, which an agent may address a reply to instead of the id.
+    """
+    results: dict[str, tuple[bool, str]] = {
+        message.tool_call_id: (message.ok, message.text)
+        for message in messages
+        if message.role == "tool" and message.tool_call_id
+    }
+    ours = {value for value in (gateway_id, handle) if value}
+    items: list[dict[str, object]] = []
+    for message in messages:
+        if message.role == "summary":
+            items.append({"kind": "note", "text": message.text})
+        elif message.role == "user":
+            items.append(_user_item(message, gateway_id))
+        elif message.role == "assistant":
+            text = message.text.strip()
+            if text:
+                items.append({"kind": "in", "text": text})
+            for call in message.tool_calls:
+                items.append(_tool_item(call.id, call.name, call.arguments, results, ours))
+    return items
+
+
+def picture_id(data: bytes) -> str:
+    """Return the name a picture is served under: a prefix of its hash, so the same file is the same address."""
+    return hashlib.sha256(data).hexdigest()[:20]
+
+
+def _user_item(message: Message, gateway_id: str) -> dict[str, object]:
+    text = strip_reply_request(message.text)
+    relay = message.relay
+    if relay is None:
+        item: dict[str, object] = {"kind": "user", "text": text}
+    elif relay.sender_id == gateway_id:
+        item = {"kind": "out", "text": text}
+    else:
+        item = {"kind": "from", "text": text, "sender": relay.sender, "via": relay.via}
+    if message.pictures:
+        # Named, not inlined: the pictures are fetched one by one and cached, not sent again with every refresh.
+        item["images"] = [
+            {"id": picture_id(picture.data), "media_type": picture.media_type, "bytes": len(picture.data)}
+            for picture in message.pictures
+        ]
+    return item
+
+
+def _tool_item(
+    call_id: str, name: str, arguments: dict[str, object], results: dict[str, tuple[bool, str]], ours: set[str]
+) -> dict[str, object]:
+    spoken_to = arguments.get("to")
+    said = arguments.get("message")
+    if name == SEND_TOOL and isinstance(spoken_to, str) and spoken_to in ours and isinstance(said, str):
+        return {"kind": "reply", "text": said.strip()}
+    item: dict[str, object] = {"kind": "tool", "name": name, "brief": brief_of(arguments)}
+    if call_id in results:
+        ok, output = results[call_id]
+        item["ok"] = ok
+        item["output"] = output if len(output) <= OUTPUT_LIMIT else output[:OUTPUT_LIMIT] + "\n..."
+    return item
+
+
+def spoken(items: Iterable[dict[str, object]]) -> int:
+    """Return how many things the session said to this gateway: what a chat counts as unread."""
+    return sum(1 for item in items if item["kind"] in SPOKEN)
+
+
+def preview(items: Sequence[dict[str, object]], limit: int = 90) -> str:
+    """Return the line a chat list shows under a name: the last thing said, with ``You:`` before what we said."""
+    for item in reversed(items):
+        kind = item["kind"]
+        if kind not in ("out", "in", "reply", "from", "user"):
+            continue
+        line = " ".join(str(item["text"]).split())
+        if not line:
+            continue
+        if kind == "out":
+            line = f"You: {line}"
+        return line if len(line) <= limit else line[: limit - 1] + "\u2026"
+    return ""