zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/dialogue/__init__.py

@@ -0,0 +1,6 @@
+"""What is said in the conversation besides the turns themselves.
+
+``mentions`` are the resources a draft can pull in with ``@``, ``ask`` is the model
+asking the reader a question, ``side`` is a question that never joins the
+conversation, and ``title`` is the small call that names a session.
+"""

zettcode/engine/dialogue/ask.py

@@ -0,0 +1,113 @@
+"""The ``ask_user`` protocol: what the model asked, and what answers it.
+
+``zett-agent`` owns the tool, the suspension and the routing; this module owns
+the little the shell and the agent have to agree on — the question parsed out of
+the event payload, and the payloads that answer it. Keeping both here means the
+panel never reads a raw payload and the agent never invents one.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from zett_agent.events import AgentEvent
+from zett_agent.extensions.ask_user import ASK_USER_EVENT_NAME, ASK_USER_RESPONSE_EVENT_NAME
+
+__all__ = [
+    "ASK_USER_RESPONSE_EVENT_NAME",
+    "AskUserQuestion",
+    "answer_payload",
+    "decline_payload",
+    "declined_answer",
+    "question_from",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class AskUserQuestion:
+    """One question the model is waiting on.
+
+    Attributes:
+        session_id: Session the question belongs to, echoed back with the answer.
+        call_id: Tool call the answer resolves; the agent routes on it.
+        question: The question, trimmed.
+        options: Choices the model offered, in display order; empty when it
+            offered none.
+        allow_multiple: Whether more than one option may be chosen.
+    """
+
+    session_id: str
+    call_id: str
+    question: str
+    options: tuple[str, ...] = ()
+    allow_multiple: bool = False
+
+
+def _options(value: object) -> tuple[str, ...]:
+    """Return the usable choices in a payload field, dropping anything else."""
+    if not isinstance(value, list):
+        return ()
+    return tuple(item.strip() for item in value if isinstance(item, str) and item.strip())
+
+
+def question_from(event: AgentEvent) -> AskUserQuestion | None:
+    """Return the question an event carries, or ``None`` when it is not one.
+
+    The payload comes from the runtime, but a malformed one must not take the
+    shell down: it is read defensively and reported as "not a question".
+    """
+    if event.name != ASK_USER_EVENT_NAME:
+        return None
+    payload = event.payload if isinstance(event.payload, dict) else {}
+    question = payload.get("question")
+    call_id = payload.get("tool_call_id")
+    if not isinstance(question, str) or not question.strip():
+        return None
+    if not isinstance(call_id, str) or not call_id:
+        return None
+    session_id = payload.get("session_id") or event.session_id
+    return AskUserQuestion(
+        session_id=str(session_id or ""),
+        call_id=call_id,
+        question=question.strip(),
+        options=_options(payload.get("options")),
+        allow_multiple=bool(payload.get("allow_multiple")),
+    )
+
+
+def answer_payload(question: AskUserQuestion, answer: str) -> dict[str, Any]:
+    """Return the response payload for a question the reader answered."""
+    return {"tool_call_id": question.call_id, "answer": answer}
+
+
+def decline_payload(question: AskUserQuestion) -> dict[str, Any]:
+    """Return the response payload for a question the reader cancelled.
+
+    ``ask_user`` has no rejection channel: the tool returns whatever payload the
+    UI sends. A cancel therefore answers with a result that says the question was
+    declined — the model reads that and carries on, instead of a suspended call
+    waiting for a reply that is never coming.
+    """
+    return {
+        "tool_call_id": question.call_id,
+        "answer": None,
+        "declined": True,
+        "reason": "the user cancelled the question",
+    }
+
+
+def declined_answer(text: str) -> bool:
+    """Return whether a tool result is the one a cancelled question leaves behind.
+
+    The tool answers with the payload the shell sent, serialized as JSON. A cancelled question carries
+    ``"declined": true`` and no answer; a row that has one is not a row that failed, it is a question nobody
+    needed to answer, and the transcript says so.
+    """
+    try:
+        result = json.loads(text)
+    except ValueError:
+        return False
+    payload = result.get("payload") if isinstance(result, dict) else None
+    return isinstance(payload, dict) and payload.get("declined") is True

zettcode/engine/dialogue/side.py

@@ -0,0 +1,197 @@
+"""Side questions: answers that never join the conversation.
+
+A side question — "btw, what does this function do?" — runs in the same session,
+so the model sees the conversation it is about, but nothing it produces joins it.
+The store writes every message of that request with ``include_in_messages=False``,
+the flag the runtime already defines as "record it, never replay it". Nothing has
+to be undone in memory afterwards: the next request rebuilds its context from the
+stored branch.
+
+The tools are reading ones for the same reason. An edit made while asking a side
+question would be invisible to the conversation that continues after it, so the
+model would carry on with a false picture of the workspace.
+
+Searching is one of them. The main agent searches with its shell and has no ``glob`` or ``grep``, but a side
+question has no shell, so it is given the two search tools here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from zett_agent.agent import AgentRunContext
+from zett_agent.extensions.base import AgentExtension
+from zett_agent.messages import UserMessage
+
+#: Attribute marking the message a side question is asked as.
+SIDE = "side"
+
+#: Attribute (and stored tag) saying who asked a side question: ``/btw``, or a plugin's own ask.
+ORIGIN = "origin"
+
+#: The origin of a side question the reader asked, which is the one a resumed transcript restores by default.
+READER = "reader"
+
+#: Attribute (and stored tag) saying the reader watched the exchange on screen.
+WATCHED = "watched"
+
+#: Tools a side question may use: the ones that only read.
+READ_ONLY_TOOLS = frozenset({"read", "read_file", "glob", "grep", "read_skill", "list_sessions", "message_history"})
+
+
+def is_reader(origin: object) -> bool:
+    """Return whether an origin names the reader, whose side questions are the ones a front end draws."""
+    return origin == READER
+
+
+def question(text: str, *, origin: str = READER, watched: bool | None = None) -> UserMessage:
+    """Return the message a side question is asked as.
+
+    Args:
+        text: The question.
+        origin: Who asked it — :data:`READER` for the reader's own ``/btw``, or the name of the plugin asking for
+            itself (``"recap"``). It is written down with the exchange, and a resumed transcript restores only what the
+            reader asked.
+        watched: Whether a reopened transcript restores this exchange. Left out, it follows ``origin``: a question the
+            reader asked comes back, a plugin's own does not. It says nothing about a front end drawing the exchange
+            now — a shell still drops a side question it did not begin — so setting it for something never drawn
+            restores a row nobody saw.
+    """
+    return UserMessage(
+        content=text,
+        attributes={SIDE: True, ORIGIN: origin, WATCHED: watched_by(origin, watched)},
+        include_in_messages=False,
+    )
+
+
+def is_side(message: object) -> bool:
+    """Return whether a message is a side question."""
+    return isinstance(message, UserMessage) and bool(getattr(message, "attributes", {}).get(SIDE))
+
+
+def _watched(values: Mapping[str, Any]) -> bool:
+    """Return whether a side question's attributes — or a stored line's tags — say the reader watched it.
+
+    ``watched`` is the answer, and it is written beside the origin on every new run, so it is what a stored exchange is
+    read from. ``origin`` is not consulted here: it says who asked, for whoever reads the file later, and the two are
+    written together, so a file that carries one without the other was not written by this program.
+
+    Without ``watched`` the answer is no. That is the conservative reading, because the two errors are not equal:
+    dropping an aside the reader saw costs a line of context, while restoring one they did not ask puts the model's own
+    instructions in their mouth. Files from before both tags hold the recap's asks and the reader's ``/btw`` looking
+    alike, and the only thing that asked on its own back then was the recap, so those are the lines this keeps off the
+    screen; a ``/btw`` from such a file goes with them, which is the price of not keeping the recap's words.
+    """
+    return bool(values.get(WATCHED, False))
+
+
+def watched_by(origin: str, watched: bool | None) -> bool:
+    """Return whether a side question asked as ``origin`` was watched, when the caller left it out.
+
+    A question the reader asked is restored; a plugin's own is not. This is the one place the rule is written: the
+    message and the request that carries it both come through here.
+    """
+    return is_reader(origin) if watched is None else watched
+
+
+def is_watched_side(message: object) -> bool:
+    """Return whether a side question's message says the reader watched it, False for anything that is not one."""
+    if not is_side(message):
+        return False
+    # ``is_side`` read ``attributes.get`` a moment ago, so a side message always holds a mapping here; the default is
+    # for the type checker, which sees only ``object``.
+    return _watched(getattr(message, "attributes", {}))
+
+
+def is_side_run(context: AgentRunContext) -> bool:
+    """Return whether the request being prepared is a side question."""
+    # Read defensively: a request that never carried an input — a compaction pass
+    # over a restored session, or a test's stand-in context — is not a side one.
+    return is_side(getattr(context, "input_message", None))
+
+
+def is_side_line(line: object) -> bool:
+    """Return whether a stored line belongs to a side question.
+
+    The store tags every line of that request, so a reader that walks the branch
+    — the replay a resumed session builds, the HTML trace an export writes — can
+    tell a side exchange from an ordinary one. The message's own
+    ``include_in_messages`` flag would not do: instructions carry it too, and
+    those are exactly what a trace wants to show.
+    """
+    tags = getattr(line, "tags", None)
+    return isinstance(tags, Mapping) and bool(tags.get(SIDE))
+
+
+def is_watched_side_line(line: object) -> bool:
+    """Return whether a stored line belongs to a side question the reader watched on screen.
+
+    The run is tagged with what the caller said when it asked, and ``watched`` alone is read back: a question a plugin
+    asked for itself stays out of a reopened transcript, so the model's instructions to itself do not come back as the
+    reader's words. ``origin`` sits beside it for whoever reads the file, and a line carrying neither tag is not
+    restored either — see :func:`_watched` for why that is the cheaper error. What a front end draws *live* is a
+    separate decision, taken where the run is begun (``app.ui.app``), not here.
+    """
+    if not is_side_line(line):
+        return False
+    # ``is_side_line`` returned True, so the line carries tags.
+    return _watched(line.tags)  # type: ignore[attr-defined]
+
+
+class SideQuestions(AgentExtension):
+    """Keep one side question's tools to reading.
+
+    The shell marks the run it is about to start, because the hook that registers
+    tools runs before the question itself is known. Pruning there rather than
+    later matters twice over: the tool list is rebuilt for every request, and the
+    guidance a prompt carries is written from that same list, so a write tool
+    dropped now is never described to the model either.
+
+    The question itself is a second signal, checked before every turn: it prunes
+    the same tools if the mark was not set, which keeps a side question read-only
+    even when something else starts it.
+    """
+
+    #: After the coding bundle, which is what registers the tools being filtered.
+    priority = 120
+
+    def __init__(self) -> None:
+        """Start with no side question pending."""
+        self._pending = False
+
+    def begin(self) -> None:
+        """Mark the run that is about to start as a side question."""
+        self._pending = True
+
+    def end(self) -> None:
+        """Forget the mark, so the next run is an ordinary one."""
+        self._pending = False
+
+    @property
+    def pending(self) -> bool:
+        """Return whether a side question is the run in flight."""
+        return self._pending
+
+    async def on_tool(self, context: AgentRunContext) -> None:
+        """Offer a side question the read tools only."""
+        if self._pending:
+            self._read_only(context)
+
+    async def before_turn(self, context: AgentRunContext) -> None:
+        """Prune again for a question that carried its own mark."""
+        if is_side_run(context):
+            self._read_only(context)
+
+    @staticmethod
+    def _read_only(context: AgentRunContext) -> None:
+        """Drop every registered tool that is not one of the reading ones, and make sure the two search tools are there."""
+        # Imported here: the tools bring the schema library, which a request that is not a side question never needs.
+        from ..tools.files import glob, grep
+
+        for name in tuple(context.tools):
+            if name not in READ_ONLY_TOOLS:
+                context.tools.pop(name, None)
+        for search in (glob, grep):
+            if search.name not in context.tools:
+                context.register_tool(search)

zettcode/engine/dialogue/title.py

@@ -0,0 +1,80 @@
+"""Session titles: one small model call that names the first exchange.
+
+A title is a nicety, not conversation data: it never enters the message history
+and it is produced by a single provider request instead of another agent turn,
+so no tools, hooks, or extra session records are involved.
+"""
+
+from __future__ import annotations
+
+import re
+
+from zett_agent.messages import SystemMessage, UserMessage
+from zett_agent.model import AgentModel, ModelEventType, ModelRequest, ReasoningEffort
+
+#: Most characters a stored title may use, matching the store's own guard.
+MAX_TITLE_CHARS = 60
+#: Most characters of each side of the exchange sent to the model.
+MAX_EXCERPT_CHARS = 1200
+
+INSTRUCTIONS = (
+    "You name conversations. Reply with a single short title of at most six words for the "
+    "exchange below, in the language the user wrote in. Reply with the title only: no quotes, "
+    "no markdown, no trailing period."
+)
+
+#: Decoration a model wraps a title in: bullets, headings, or a list number.
+_LEADING_MARKER = re.compile(r"^(?:[-*\u2022\u25aa>#]+\s*|\d+[.)]\s+)+")
+#: Trailing punctuation that only marks the end of a sentence.
+_TRAILING = ".:;,\u3002"
+
+
+async def summarize_title(
+    model: AgentModel,
+    *,
+    question: str,
+    answer: str,
+    effort: ReasoningEffort = ReasoningEffort.LOW,
+) -> str | None:
+    """Return a short title for the first exchange, or ``None`` when there is none.
+
+    Args:
+        model: Model to ask; the request carries no tools, so the provider's own
+            retry policy applies and no agent turn or session record is created.
+        question: The user's first message.
+        answer: The assistant's reply to it.
+        effort: How hard the model thinks about it. Cheap by default; the caller moves it to a
+            level the model takes, because an endpoint that rejects one fails the request.
+    """
+    request = ModelRequest(
+        messages=[
+            SystemMessage(content=INSTRUCTIONS),
+            UserMessage(content=f"User: {excerpt(question)}\n\nAssistant: {excerpt(answer)}"),
+        ],
+        reasoning_effort=effort,
+    )
+    reply = ""
+    async for event in model.stream(request):
+        if event.type is ModelEventType.TEXT_DELTA:
+            reply += event.delta
+    return clean_title(reply)
+
+
+def excerpt(text: str) -> str:
+    """Collapse one side of the exchange to a single bounded paragraph."""
+    return " ".join(text.split())[:MAX_EXCERPT_CHARS]
+
+
+def clean_title(reply: str) -> str | None:
+    """Reduce a model reply to one title line, or ``None`` when nothing is left.
+
+    Models answer with a bullet, a heading, backticks, or a quoted sentence even
+    when told not to, so the first non-empty line is unwrapped before the length
+    cap is applied. A reply that is only punctuation leaves no title at all.
+    """
+    for line in reply.splitlines():
+        cleaned = _LEADING_MARKER.sub("", line.strip())
+        cleaned = cleaned.strip("`*_# \t").strip("\"'").strip().rstrip(_TRAILING).strip()
+        if cleaned:
+            return cleaned[:MAX_TITLE_CHARS].strip() or None
+    return None