zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/agent/conversation/replay.py

@@ -0,0 +1,198 @@
+"""Rebuild a transcript from a stored branch, the way ``/resume`` restores one.
+
+The walk lives here, apart from the shell, so that how a stored turn, a tool result,
+or the reasoning that came with an answer becomes a row is written down once and is
+the same whoever asks.
+
+The transcript keeps only its newest ``max_entries`` entries, so a long branch is
+not replayed from its beginning: the walk starts where the entries that will be kept
+begin, and the rest of the branch contributes only what is recorded beside its
+messages — the usage of each reply — which needs no message decoded at all.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import cast
+
+from zett_agent.messages import AnyMessage, AssistantMessage, SystemMessage, ToolMessage, UserMessage
+
+from zettcode.config import DEFAULT_TRANSCRIPT_MAX_ENTRIES
+from zettcode.engine.dialogue.ask import declined_answer
+from zettcode.engine.dialogue.side import is_side_line, is_watched_side_line
+from zettcode.engine.extensions.usage import UsageSnapshot, session_usage
+from zettcode.engine.server_tools import ServerToolRun, answer_after_tools, describe_output, runs_in_blocks
+from zettcode.engine.storage import MessageLine, Session
+from zettcode.messaging.relayed import relay_of
+from zettcode.plugin_api.entries import EntryStatus
+from zettcode.presenters.presenters import DEFAULT_PRESENTERS, Presenters
+
+from .rendering import DEFAULT_RENDERERS, Renderers
+from .stops import stop_text
+from .transcript import Transcript
+
+#: Entries of margin past the ones a window has to hold. Counting what a message will
+#: add is an upper bound — consecutive replies with no row between them share one
+#: answer, and a result whose call is before the window adds nothing — so the window
+#: starts a little earlier than the count says it needs to.
+WINDOW_SLACK = 64
+
+
+@dataclass(frozen=True, slots=True)
+class Replayed:
+    """What one stored branch replays into.
+
+    Attributes:
+        transcript: The newest entries of the branch, ready to render or install.
+        usage: Totals accumulated from the usage every stored reply recorded, the
+            ones before the transcript's window included.
+        lines: The whole active branch, oldest first.
+    """
+
+    transcript: Transcript
+    usage: UsageSnapshot
+    lines: Sequence[MessageLine]
+
+    @property
+    def history(self) -> tuple[AnyMessage, ...]:
+        """Return the messages a request would carry, oldest first.
+
+        Everything on the branch that is not an instruction or a side question. It is
+        worked out when asked for, because it needs every message on the branch
+        decoded, which restoring a session into the shell never wants.
+        """
+        return tuple(
+            line.message[0]
+            for line in self.lines
+            if not is_side_line(line)
+            and line.message[0].include_in_messages
+            and not isinstance(line.message[0], SystemMessage)
+        )
+
+
+def entries_added_by(message: AnyMessage) -> int:
+    """Return the most rows replaying one message adds to the transcript."""
+    match message:
+        case UserMessage():
+            return 1
+        case AssistantMessage():
+            stopped = message.stop is not None and not message.stop.ok
+            return (
+                bool(message.reasoning)
+                + bool(message.content)
+                + len(message.tool_calls)
+                + len(runs_in_blocks(message.replay_blocks))
+                + stopped
+            )
+        case _:
+            return 0
+
+
+def window_start(lines: Sequence[MessageLine], entries: int) -> int:
+    """Return the index of the line to start replaying from to end with ``entries`` rows.
+
+    The branch is walked from its newest line, so the only messages looked inside are
+    the ones the window will replay anyway; a short branch returns 0 and is replayed
+    whole. A side run nobody watched is skipped here as it is skipped below, or the
+    count would reach its target on rows the window then drops and the restored
+    transcript would hold fewer rows than it was asked for.
+
+    Args:
+        lines: The active branch, oldest first.
+        entries: Rows the window has to hold.
+    """
+    wanted = entries + WINDOW_SLACK
+    seen = 0
+    for index in range(len(lines) - 1, -1, -1):
+        if is_side_line(lines[index]) and not is_watched_side_line(lines[index]):
+            continue
+        seen += entries_added_by(lines[index].message[0])
+        if seen >= wanted:
+            return index
+    return 0
+
+
+def replay(
+    session: object,
+    *,
+    renderers: Renderers = DEFAULT_RENDERERS,
+    presenters: Presenters = DEFAULT_PRESENTERS,
+    frame: int = 0,
+    max_entries: int = DEFAULT_TRANSCRIPT_MAX_ENTRIES,
+) -> Replayed:
+    """Rebuild a session's active branch into entries, totals, and messages.
+
+    Args:
+        session: The parsed session (the ``records`` of an SDK ``StoredSession``; typed ``object`` because its type is
+            the engine's, which the views do not import).
+        renderers: Chain that phrases tool rows.
+        presenters: How each row is drawn.
+        frame: The animation step the rebuilt rows start at.
+        max_entries: How many entries the transcript keeps. Only the lines that
+            produce them are decoded and walked; the older ones add their usage to
+            the totals and nothing else.
+    """
+    lines = cast("Session", session).branch()
+    start = window_start(lines, max_entries)
+    transcript = Transcript(renderers=renderers, presenters=presenters, max_entries=max_entries)
+    transcript.frame = frame
+    for line in lines[start:]:
+        # A side question the reader watched is shown again — restoring the session restores the transcript they were
+        # looking at — while staying out of ``history``, which is what the next request would carry. One nobody watched
+        # is left out whole, question and answer: a plugin's recap is asked with nothing on screen, so restoring it
+        # would put words in the conversation that were never said there.
+        side = is_side_line(line)
+        if side and not is_watched_side_line(line):
+            continue
+        message = line.message[0]
+        match message:
+            case UserMessage():
+                # A message whose ``@`` references expanded carries the text the
+                # reader typed as an attribute; the row restores that, while
+                # ``history`` keeps the text the model was given.
+                original = message.attributes.get("prompt")
+                shown = original if isinstance(original, str) and original else message.text
+                relayed = relay_of(message.attributes, shown)
+                if relayed is not None and not side:
+                    transcript.relayed_message(relayed)
+                else:
+                    transcript.user_message(shown, side=side)
+            case AssistantMessage():
+                if message.reasoning:
+                    transcript.restore_thinking(message.reasoning, line.timing.reasoning_duration_ns)
+                runs = runs_in_blocks(message.replay_blocks)
+
+                def hosted(rows: Sequence[ServerToolRun] = runs) -> None:
+                    """Add the rows of the tools the endpoint ran, each closed by its own result."""
+                    for run in rows:
+                        transcript.start_tool(run.call_id, run.name, run.arguments)
+                        transcript.complete_tool(
+                            run.call_id,
+                            describe_output(run),
+                            status=EntryStatus.FAILED if run.error else EntryStatus.COMPLETED,
+                            wait=False,
+                        )
+
+                # A hosted tool has no message of its own: its call and result are both in the answer's blocks, kept
+                # because the provider needs them back. Where the answer's text sits in those blocks is where the row
+                # goes relative to it, so a reopened session reads in the order the run did.
+                if not answer_after_tools(message.replay_blocks) and message.content:
+                    transcript.append_answer(message.content)
+                hosted()
+                if answer_after_tools(message.replay_blocks) and message.content:
+                    transcript.append_answer(message.content)
+                for call in message.tool_calls:
+                    transcript.start_tool(call.id, call.name, call.arguments)
+                if message.stop is not None and not message.stop.ok:
+                    transcript.error(stop_text(message.stop))
+            case ToolMessage():
+                status = EntryStatus.COMPLETED if message.success else EntryStatus.FAILED
+                if message.name == "ask_user" and declined_answer(message.text):
+                    # A cancelled question is an answer of its own, not a failure.
+                    status = EntryStatus.SKIPPED
+                transcript.complete_tool(message.tool_call_id, message.text, status=status, wait=False)
+            case _:
+                continue
+    transcript.finish_restored_tools()
+    return Replayed(transcript=transcript, usage=session_usage(lines), lines=lines)

zettcode/app/agent/conversation/shimmer.py

@@ -0,0 +1,256 @@
+"""The show the header plays for a switch to the top of the scale: light crossing the whole row, right to left.
+
+Reaching ``max`` or ``ultra`` is the expensive thing a reader can do here, and the header marks it with an
+animation of its own rather than the gauge every other switch gets (:mod:`.effort_gauge`). Light crosses the
+header several times; the first pass ignites the right segment as it goes and the later ones glint over the
+left. A frame is a value without a colour, like the gauge's: the painter chooses the colours from the theme.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+#: The levels at the top of the scale. Reaching one is the expensive thing a reader can do here, and the
+#: header marks it with a show of its own rather than the gauge every other switch gets.
+SHIMMER_LEVELS = frozenset({"max", "ultra"})
+
+#: How fast the light crosses the header, in columns a second, pass by pass. It is a speed rather than a time,
+#: because a time would send the light across a wide terminal at twice the pace it crosses a narrow one. The
+#: first pass is the slowest, so there is time to watch it light the corner as it goes, and each later one is a
+#: little quicker; the top of the scale gets one pass more. The pace is chosen against the frame: at 120 frames a
+#: second the slowest pass moves the light about a cell per frame, which is what makes it read as one continuous
+#: crossing rather than a light that sits still and then jumps a column — at half this pace most frames carried
+#: no movement at all, which is the stutter a reader sees as jerky.
+SHIMMER_SPEEDS: dict[str, tuple[float, ...]] = {
+    "max": (110.0, 140.0, 170.0, 200.0),
+    "ultra": (110.0, 140.0, 170.0, 200.0, 230.0),
+}
+
+#: How far across its trip a pass is when the next one sets off, so the light keeps coming. High enough that a
+#: pass is still crossing when the next is well under way: the row carries light the whole time.
+SHIMMER_OVERLAP = 0.5
+
+#: Seconds the corner stays lit after the last pass has gone, before it hands the header back. It is a hold
+#: rather than a fade of nothing: the corner keeps the light the first pass put on it, and the row would look
+#: abandoned if it went straight back to the resting header the moment the last pass left.
+SHIMMER_TAIL = 1.6
+
+#: Seconds the row takes to arrive and to leave.
+SHIMMER_FADE_IN_SECONDS = 0.25
+SHIMMER_FADE_OUT_SECONDS = 0.8
+
+#: Seconds the slowest pass is allowed to take, however wide the terminal: past this the light speeds up rather
+#: than keep a very wide header waiting.
+SHIMMER_LONGEST_PASS = 2.6
+
+#: Half the width, in cells, of the light that crosses the header (its halo), and of the white-hot core inside it.
+#: The halo is what makes the crossing visible at a glance; the core is the hot centre of it. The core is wide
+#: enough to cover a few cells, so the glint is a band of light rather than a single cell that flickers.
+SHIMMER_HALO = 8.0
+SHIMMER_CORE = 4.0
+
+#: Cells past either end of the row a pass starts and finishes, so the light enters and leaves.
+SHIMMER_RUNWAY = 8
+
+#: Twinkles either side of the word, by level, stepped this many times a second.
+SHIMMER_SPARKS: dict[str, tuple[str, ...]] = {
+    "max": ("\u2726", " ", "\u00b7", " "),
+    "ultra": ("\u2726", "\u2727", "\u00b7", "\u2727"),
+}
+SHIMMER_SPARK_RATE = 14
+
+#: Columns between the last gauge cell and the word's first letter (a gap, a sparkle, a gap), and after the word.
+SHIMMER_BEFORE_WORD = 3
+SHIMMER_AFTER_WORD = 2
+
+
+def shimmer_schedule(level: str, reach: int) -> tuple[tuple[float, float], ...]:
+    """Return when each pass of light is on, in seconds from the start of the show: ``(start, end)``.
+
+    A pass crosses ``reach`` columns and its runway at its level's speed (but takes no longer than
+    :data:`SHIMMER_LONGEST_PASS`, scaled by its speed), and the next sets off once this one is
+    :data:`SHIMMER_OVERLAP` of the way across.
+    """
+    trip = reach + 2 * SHIMMER_RUNWAY
+    windows = []
+    start = 0.0
+    slowest = SHIMMER_SPEEDS[level][0]
+    for speed in SHIMMER_SPEEDS[level]:
+        duration = min(trip / speed, SHIMMER_LONGEST_PASS * slowest / speed)
+        windows.append((start, start + duration))
+        start += duration * SHIMMER_OVERLAP
+    return tuple(windows)
+
+
+def shimmer_seconds(level: str, reach: int) -> float:
+    """Return how long the show lasts for a header ``reach`` columns wide: the last pass, then the tail."""
+    return shimmer_schedule(level, reach)[-1][1] + SHIMMER_TAIL
+
+
+@dataclass(frozen=True, slots=True)
+class ShimmerFrame:
+    """One instant of the show a switch to the top of the scale plays in the header, without a colour.
+
+    The row is ``model \u00b7 gauge  \u2726 word \u2726`` and every list here has one entry per column of it, from the
+    first letter of the model's name to the last sparkle, so the painter lays them over the spans it draws. The
+    width never changes during the show: the sparkles are always there, blank or not, so the right-aligned row
+    does not shiver as they twinkle.
+
+    Attributes:
+        lead: Columns before the gauge: the model's name and the separator after it.
+        cells: Cells in the gauge.
+        lit_cells: How many of them the level reaches; the rest stay rail.
+        word: The level being shown.
+        glow: How much of the light's halo is on each column, ``0`` to ``1``.
+        core: How much of its white-hot core is, ``0`` to ``1``; always at most the glow.
+        ignited: Whether the first pass has gone over each column. The light travels right to left, so the
+            columns it has left behind are the ones to the right of it.
+        glitter: A fast twinkle on each column; nothing at ``max``, and on the lit part of the row at ``ultra``.
+        sparks: The sparkle drawn left of the word and the one drawn right of it.
+        heat: Where on the scale the level sits, ``0`` to ``1``; the colour ramp reads it.
+        presence: How much of the show is there: it rises, holds and falls, and the painter blends every colour
+            toward the resting header by what is missing.
+        reach: Columns of the header the light crosses, from the right edge to the left one.
+        bands: Where each pass of light is now, as its distance from the right edge.
+    """
+
+    lead: int
+    cells: int
+    lit_cells: int
+    word: str
+    glow: tuple[float, ...]
+    core: tuple[float, ...]
+    ignited: tuple[bool, ...]
+    glitter: tuple[float, ...]
+    sparks: tuple[str, str]
+    heat: float
+    presence: float
+    reach: int
+    bands: tuple[float, ...]
+
+    @property
+    def width(self) -> int:
+        """Return the columns the row takes, which does not change from one frame to the next."""
+        return len(self.glow)
+
+    def light(self, distance: float) -> tuple[float, float]:
+        """Return the halo and the core of the light at a column ``distance`` cells from the right edge.
+
+        The right segment is described by :attr:`glow` and :attr:`core`; this is the same light for any other
+        column of the header, which is how the left segment glints as the light goes over it.
+        """
+        halo = max((_profile(abs(distance - centre), SHIMMER_HALO) for centre in self.bands), default=0.0)
+        core = max((_profile(abs(distance - centre), SHIMMER_CORE) for centre in self.bands), default=0.0)
+        return halo, core
+
+    @property
+    def word_start(self) -> int:
+        """Return the column the word's first letter is in."""
+        return self.lead + self.cells + SHIMMER_BEFORE_WORD
+
+
+def shimmer_width(lead: int, cells: int, word: str) -> int:
+    """Return the columns of the show's row: the lead, the gauge, the word with its sparkles."""
+    return lead + cells + SHIMMER_BEFORE_WORD + len(word) + SHIMMER_AFTER_WORD
+
+
+def _profile(distance: float, half_width: float) -> float:
+    """Return the brightness of light ``distance`` cells from its centre: a cosine, zero past its reach."""
+    if distance >= half_width:
+        return 0.0
+    return 0.5 * (1 + math.cos(math.pi * distance / half_width))
+
+
+def _centre(window: tuple[float, float], elapsed: float, reach: int) -> float | None:
+    """Return where a pass of light is, as its distance from the right edge, or ``None`` when it is not on.
+
+    It enters past the right edge and leaves past the left one, ``reach`` columns away. The ease is gentle — half
+    a smooth step, half a straight line — so the light leans into the trip and out of it without the
+    middle of the trip being much quicker than the pace the pass was given.
+    """
+    start, end = window
+    if not start <= elapsed <= end:
+        return None
+    along = (elapsed - start) / (end - start)
+    eased = 0.5 * along + 0.5 * along * along * (3 - 2 * along)
+    return -SHIMMER_RUNWAY + eased * (reach + 2 * SHIMMER_RUNWAY)
+
+
+def shimmer_frame(
+    current: str,
+    levels: Sequence[str],
+    *,
+    lead: int,
+    reach: int,
+    progress: float,
+) -> ShimmerFrame | None:
+    """Return the header's show for a switch to the top of the scale, ``progress`` of the way through it.
+
+    Light crosses the whole header from right to left, several times: the first pass ignites the right segment,
+    laying the gauge and the word down in the hot end of the scale's colours as it goes, and the later passes are
+    a little quicker, each with a white-hot core inside a wide halo. They keep going over the left segment, so
+    the whole row glints, not just the corner that changed. Sparkles twinkle either side of the word once it is
+    lit. Everything is a function of ``progress``, the fraction of the show's time that has gone, so a slow
+    terminal drops frames instead of stretching the show.
+
+    Args:
+        current: The level reached. One that is not at the top of the scale answers ``None``: the ordinary gauge
+            is the animation for it.
+        levels: The configured levels, cheapest first.
+        lead: Columns of the right segment before the gauge, which the painter knows and this does not.
+        reach: Columns of the header, which is how far the light travels and, at a fixed speed, how long the
+            show lasts (:func:`shimmer_seconds`). At least as wide as the row itself.
+        progress: ``0`` at the start through ``1`` at the end; outside that range the answer is ``None``, which
+            is the caller's cue to release the frame loop.
+    """
+    if not 0.0 <= progress < 1.0 or current not in SHIMMER_LEVELS or current not in levels:
+        return None
+    count = len(levels)
+    width = shimmer_width(lead, count, current)
+    reach = max(reach, width)
+    seconds = shimmer_seconds(current, reach)
+    elapsed = progress * seconds
+    schedule = shimmer_schedule(current, reach)
+    target = levels.index(current)
+    last = max(1, count - 1)
+    bands = tuple(centre for window in schedule if (centre := _centre(window, elapsed, reach)) is not None)
+    first = schedule[0]
+    # The columns the first pass has gone over are the ones nearer the right edge than it is.
+    first_centre = _centre(first, elapsed, reach)
+    if first_centre is None:
+        first_centre = -SHIMMER_RUNWAY if elapsed < first[0] else reach + SHIMMER_RUNWAY
+    steps = int(elapsed * SHIMMER_SPARK_RATE)
+    glow, core, ignited, glitter = [], [], [], []
+    for column in range(width):
+        distance = width - 1 - column
+        glow.append(max((_profile(abs(distance - centre), SHIMMER_HALO) for centre in bands), default=0.0))
+        core.append(max((_profile(abs(distance - centre), SHIMMER_CORE) for centre in bands), default=0.0))
+        ignited.append(distance < first_centre)
+        if current == "ultra" and distance < first_centre:
+            twinkle = 0.5 + 0.5 * math.sin(elapsed * 31 + column * 2.3)
+            glitter.append(max(0.0, twinkle - 0.62) / 0.38)
+        else:
+            glitter.append(0.0)
+    sparks = SHIMMER_SPARKS[current]
+    left_column = width - SHIMMER_AFTER_WORD - len(current) - 2
+    right_column = width - 1
+    left = sparks[steps % len(sparks)] if ignited[left_column] else " "
+    right = sparks[(steps + 2) % len(sparks)] if ignited[right_column] else " "
+    presence = min(1.0, elapsed / SHIMMER_FADE_IN_SECONDS, (seconds - elapsed) / SHIMMER_FADE_OUT_SECONDS)
+    return ShimmerFrame(
+        lead,
+        count,
+        target + 1,
+        current,
+        tuple(glow),
+        tuple(core),
+        tuple(ignited),
+        tuple(glitter),
+        (left, right),
+        target / last,
+        max(0.0, presence),
+        reach,
+        bands,
+    )

zettcode/app/agent/conversation/stops.py

@@ -0,0 +1,57 @@
+"""Say why a model stopped when it did not finish, in a sentence a reader can act on.
+
+A model step ends in one of a few ways the library names (:class:`~zett_agent.stop.StopReason`), and only two are
+normal: it finished, or it asked for tools. Every other ending leaves a reply that is missing, cut off, or not what the
+model would have said, and a row that only says how long the request took would let that pass for an answer.
+
+The same sentence is used live (an event arrives) and when a stored session is shown again (the message carries the
+stop), so what was seen is what is seen again.
+"""
+
+from __future__ import annotations
+
+from zett_agent.stop import StopInfo, StopReason
+
+#: What to do about each ending the reader can do something about. A refusal has none: the same input is declined again.
+_NEXT = {
+    StopReason.MAX_OUTPUT: "/continue asks the model to carry on from there.",
+    StopReason.INTERRUPTED: "/continue asks the model to start that reply again.",
+    StopReason.PAUSED: "/continue picks the request up where the provider paused it.",
+    StopReason.CONTEXT_FULL: "/compact summarizes the conversation to make room, or /new starts afresh.",
+    StopReason.REFUSAL: "Rephrase the request, or choose another model with /model.",
+}
+
+#: Why it stopped, in the reader's terms, by reason.
+_WHAT = {
+    StopReason.MAX_OUTPUT: "The reply reached the model's output limit and is cut off.",
+    StopReason.INTERRUPTED: "The reply was cut off before the model finished it.",
+    StopReason.PAUSED: "The provider paused the reply before it was done.",
+    StopReason.CONTEXT_FULL: "The context window filled up, so the reply stopped short.",
+    StopReason.REFUSAL: "The model declined this request.",
+    StopReason.OTHER: "The model stopped for a reason ZettCode does not know, so the reply may be incomplete.",
+}
+
+
+def stop_text(stop: StopInfo) -> str:
+    """Return the line that says a model step ended abnormally, with what the provider said and what to try.
+
+    Args:
+        stop: How the step ended; one that ended normally has nothing to say and gives an empty string.
+    """
+    if stop.ok:
+        return ""
+    parts = [_WHAT.get(stop.reason, _WHAT[StopReason.OTHER])]
+    said = stop.message or stop.category or (stop.raw if stop.raw not in (None, stop.reason.value) else None)
+    if said:
+        label = f"{stop.category}: " if stop.category and stop.message and stop.category != stop.message else ""
+        parts.append(f"The provider said: {label}{said}")
+    withheld = stop.detail.get("withheld_tool_calls")
+    if isinstance(withheld, (list, tuple)) and withheld:
+        names = ", ".join(sorted({str(name) for name in withheld}))
+        parts.append(f"It had asked to run {names}; that was not done.")
+    if stop.recommended_model:
+        parts.append(f"The provider suggests {stop.recommended_model}.")
+    advice = _NEXT.get(stop.reason)
+    if advice:
+        parts.append(advice)
+    return " ".join(part if part.endswith((".", "!", "?")) else f"{part}." for part in parts)

zettcode/app/agent/conversation/tips.py

@@ -0,0 +1,86 @@
+"""Small tips for the reader, shown under the waiting row while a request runs.
+
+A request can take a while and the screen has nothing to say meanwhile, so it says something that might be
+useful: a command, a key, a thing the program does that a reader would not find by typing. Each tip is one
+sentence that names what to type, and each is true of this program as it is: ``tests/test_tips.py`` holds
+that every command a tip names exists.
+
+The tips are not chosen for the request (they are not about it): they come in an order that is different each
+time the program starts, and each request begins one tip further along, so a reader who sends ten requests sees
+ten different tips before one comes round again.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable, MutableSequence, Sequence
+
+from zettcode.tui import OPTION
+
+#: What the reader may be told, in the words they will see.
+TIPS: tuple[str, ...] = (
+    "Type while it works: your message can steer this request, or wait and follow it.",
+    "Press Shift-Enter (or Alt-Enter) to add a line to your message instead of sending it.",
+    "Type @ to mention a file or a skill. A file is read when the message is sent.",
+    "Type @ to mention another running ZettCode session; the model can pass your message to it.",
+    "/btw <question> is answered on the side and never joins the conversation.",
+    "/bash opens a full-screen command line: your shell's history, Tab completion, and coloured output.",
+    "In /bash, Tab completes git subcommands and branches, and Ctrl-C stops a running command.",
+    "/compact summarizes the conversation now, instead of waiting for the window to fill.",
+    "/context shows what is filling the context window, and where this session is stored.",
+    "/effort <level> sets how much the model reasons before it answers.",
+    "/permission changes how much of the shell may run without asking, even in the middle of a request.",
+    "/resume picks up an earlier session; /fork carries this one into a new session.",
+    "/title names this session; /export writes it to a standalone HTML file.",
+    "/model changes the model for the next request, and /config adds or removes models.",
+    "/theme dark or /theme light switches the palette in one step.",
+    "Ctrl-R searches what you have sent before; Up recalls the last message.",
+    "Ctrl-V attaches an image from the clipboard, for a model that takes images.",
+    "Page Up scrolls the conversation, and Esc jumps back to the newest line.",
+    f"{OPTION.capitalize()}-\u2191/\u2193 (or Ctrl-\u2191/\u2193) jumps to the previous or next message you sent.",
+    "Drag in the conversation to copy text. Hold Shift or Alt to use your terminal's own selection.",
+    "Put project instructions in AGENTS.md and they are given to the model with every request.",
+    "A SKILL.md in ~/.zettcode/skills teaches ZettCode a job it can repeat.",
+    "/usage shows tokens, cache and cost by day, model and session; /resume lists them per session.",
+    "/statusline chooses what the header and the status line show, and turns the pet on.",
+    "/pet picks a companion that sleeps while idle and works while a request runs; drag it anywhere.",
+    "/plugins can turn self-compaction on or off: the model decides when to compact its own context.",
+    "zettcode resume <id> opens a stored session; zettcode update installs the newest release.",
+    "zettcode doctor checks every configured model from a shell, with no session started.",
+    "zettcode --full skips every shell question and the sandbox for that run; /permission can change it later.",
+    "Press Esc to stop a request; /continue picks it up again where it left off.",
+    "A plugin is a Python package: install it and ZettCode gains its commands, tools, themes or pets.",
+    "zettcode plugin install owner/repo adds a plugin; restart ZettCode to load it.",
+    "/hub shows the session graph, the running sessions, and every daemon on this machine.",
+    "zettcode daemon spawn starts a background agent; /hub lists it and send_message reaches it.",
+    "zettcode gateway opens a web page for this machine's sessions and daemons.",
+    "/code-review asks for a review of the current change before you hand it over.",
+    'Memory is off by default; [plugins] enable = ["memory"] turns it on.',
+    "When memory is on, tell the agent what to remember; it keeps personal and project notes current.",
+    "These tips can be turned off: tips = false under [transcript] in the configuration.",
+)
+
+
+class TipDeck:
+    """Hands each request its tips, beginning one further along than the request before.
+
+    Args:
+        tips: What to hand out.
+        shuffle: Puts them in an order once, when the program starts; ``random.shuffle`` by default, injectable so
+            a test can fix the order.
+    """
+
+    def __init__(
+        self, tips: Sequence[str] = TIPS, *, shuffle: Callable[[MutableSequence[str]], None] = random.shuffle
+    ) -> None:
+        self._tips = list(tips)
+        shuffle(self._tips)
+        self._requests = 0
+
+    def next(self) -> tuple[str, ...]:
+        """Return all the tips in the order this request will show them: the first it shows is the one that follows."""
+        if not self._tips:
+            return ()
+        start = self._requests % len(self._tips)
+        self._requests += 1
+        return tuple(self._tips[start:] + self._tips[:start])