zettcode-recap 0.1.0__tar.gz

zettcode_recap-0.1.0/.gitignore

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

zettcode_recap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chang-LeHung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zettcode_recap-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: zettcode-recap
+Version: 0.1.0
+Summary: A ZettCode plugin: /recap sums up where the session is, and does so on its own when you step away
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode/tree/main/plugins/zettcode-recap
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: plugin,productivity,recap,summary,zettcode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zettcode<0.4,>=0.3
+Description-Content-Type: text/markdown
+
+# zettcode-recap
+
+A ZettCode plugin. It adds `/recap`, and writes one on its own when you step away.
+
+A recap is one sentence about where the session is: the goal, what is done, and the next thing to do. It is for a
+reader coming back to a long conversation — the model's own context is not touched, and neither the question nor the
+answer is stored as part of the conversation.
+
+- **`/recap`** writes one now, whatever the clock says. It needs a request to have finished. While the model answers,
+  the pinned row says `Recap … writing`, and Ctrl-C or Escape stops it; the answer follows as a quoted message.
+- **On its own**, once no new turn has started for long enough and the conversation is worth summarising: at least 3
+  messages you typed, and at least 2 since the last recap. The delay is `min(after_seconds, 0.8 × cache_ttl_seconds)`,
+  which is 180 seconds by default (the provider's prompt cache is likely cold by then, so waiting longer only costs
+  more). Any new turn cancels a recap that is waiting or being written: it would be news about a conversation that
+  has moved on. It is the reader's own activity that is measured, not the window — somebody reading the last answer
+  is still there, and somebody who switched to another application after a turn is as idle as one reading.
+
+The summary is requested with `cache="read"`: the conversation's warm prompt-cache prefix is reused, and the recap's
+own words are not written into the cache. It runs with no tools, a 60-second deadline, and a prompt that asks for
+under 40 words and no markdown.
+
+## Settings
+
+Each setting has a default and can be overridden in `config.toml`; your value wins:
+
+```toml
+[plugins.recap]
+after_seconds = 180       # how long no new turn may start
+cache_ttl_seconds = 300   # the provider's prompt-cache lifetime; the delay is 0.8 of it
+min_messages = 3          # messages you typed before a recap is worth writing
+min_since_recap = 2       # and messages since the last one
+```
+
+A value of the wrong type is refused when the plugin loads, naming the table and the key.
+
+The automatic recap needs nothing of the terminal but turns; the focus hook the shell offers is not used. A recap
+waiting when the program exits ends with it.
+
+## Install
+
+From a checkout of this repository:
+
+    uv tool install --force --with ./plugins/zettcode-recap zettcode
+
+or, with pip in the environment ZettCode runs in:
+
+    pip install ./plugins/zettcode-recap
+
+There is no `zettcode[recap]` extra yet: the plugin has not been released, and an extra that names a package no index
+carries would break `pip install "zettcode[recap]"`. The release workflow is in place (`recap-v*`), and the extra
+lands with the first release.
+
+It runs on ZettCode 0.3 and later (`zettcode>=0.3,<0.4`), whose terminal group has the turn hooks this plugin is
+built on.

zettcode_recap-0.1.0/README.md

@@ -0,0 +1,54 @@
+# zettcode-recap
+
+A ZettCode plugin. It adds `/recap`, and writes one on its own when you step away.
+
+A recap is one sentence about where the session is: the goal, what is done, and the next thing to do. It is for a
+reader coming back to a long conversation — the model's own context is not touched, and neither the question nor the
+answer is stored as part of the conversation.
+
+- **`/recap`** writes one now, whatever the clock says. It needs a request to have finished. While the model answers,
+  the pinned row says `Recap … writing`, and Ctrl-C or Escape stops it; the answer follows as a quoted message.
+- **On its own**, once no new turn has started for long enough and the conversation is worth summarising: at least 3
+  messages you typed, and at least 2 since the last recap. The delay is `min(after_seconds, 0.8 × cache_ttl_seconds)`,
+  which is 180 seconds by default (the provider's prompt cache is likely cold by then, so waiting longer only costs
+  more). Any new turn cancels a recap that is waiting or being written: it would be news about a conversation that
+  has moved on. It is the reader's own activity that is measured, not the window — somebody reading the last answer
+  is still there, and somebody who switched to another application after a turn is as idle as one reading.
+
+The summary is requested with `cache="read"`: the conversation's warm prompt-cache prefix is reused, and the recap's
+own words are not written into the cache. It runs with no tools, a 60-second deadline, and a prompt that asks for
+under 40 words and no markdown.
+
+## Settings
+
+Each setting has a default and can be overridden in `config.toml`; your value wins:
+
+```toml
+[plugins.recap]
+after_seconds = 180       # how long no new turn may start
+cache_ttl_seconds = 300   # the provider's prompt-cache lifetime; the delay is 0.8 of it
+min_messages = 3          # messages you typed before a recap is worth writing
+min_since_recap = 2       # and messages since the last one
+```
+
+A value of the wrong type is refused when the plugin loads, naming the table and the key.
+
+The automatic recap needs nothing of the terminal but turns; the focus hook the shell offers is not used. A recap
+waiting when the program exits ends with it.
+
+## Install
+
+From a checkout of this repository:
+
+    uv tool install --force --with ./plugins/zettcode-recap zettcode
+
+or, with pip in the environment ZettCode runs in:
+
+    pip install ./plugins/zettcode-recap
+
+There is no `zettcode[recap]` extra yet: the plugin has not been released, and an extra that names a package no index
+carries would break `pip install "zettcode[recap]"`. The release workflow is in place (`recap-v*`), and the extra
+lands with the first release.
+
+It runs on ZettCode 0.3 and later (`zettcode>=0.3,<0.4`), whose terminal group has the turn hooks this plugin is
+built on.

zettcode_recap-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "zettcode-recap"
+description = "A ZettCode plugin: /recap sums up where the session is, and does so on its own when you step away"
+readme = "README.md"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "plugin", "recap", "summary", "productivity"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Software Development :: User Interfaces",
+  "Typing :: Typed",
+]
+dependencies = [
+  # The plugin API: `PluginContext`, `TuiPlugin`, and the terminal group's focus and turn-end hooks, which the 0.3
+  # line added.
+  "zettcode>=0.3,<0.4",
+]
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode/tree/main/plugins/zettcode-recap"
+Issues = "https://github.com/Chang-LeHung/zettcode/issues"
+
+[project.entry-points."zettcode.plugins"]
+recap = "zettcode_recap:RecapPlugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/zettcode_recap/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode_recap"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[dependency-groups]
+dev = ["pytest", "pytest-asyncio"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

zettcode_recap-0.1.0/src/zettcode_recap/__init__.py

@@ -0,0 +1,301 @@
+"""``/recap``: a short account of what this session is doing, for a reader who stepped away.
+
+The plugin watches the turns of the conversation: a turn ending arms a wait, and a turn starting cancels it. When the
+reader has not started a new turn for long enough, it asks the session's model for one small summary, reusing the
+conversation's warm prompt cache without writing its own content into it (``cache="read"``). ``/recap`` asks for one
+at once.
+
+The wait is about the reader's own activity, not about the window: somebody reading the last answer is still there,
+and somebody who switched to another application after a turn is as idle as one reading. So the clock is "since the
+last turn ended", and any new turn — typed, from another session, or started by a command — cancels it.
+
+It never joins the conversation: the question and the answer are a side question, so the next turn does not read
+them, and it is shown as a markdown message whose text is a blockquote — the quote the renderer already draws, with
+nothing of its own in the transcript. Nothing about the model's own context changes.
+
+The delay is ``min(after_seconds, 0.8 × cache_ttl_seconds)``, defaulting to ``min(180, 0.8 × 300)`` = 180 seconds:
+after that long away, a provider's cached prefix is likely gone, so waiting longer would buy a colder, dearer
+summary. All four numbers are written in the plugin's own table, and the reader's value wins:
+
+    [plugins.recap]
+    after_seconds = 180       # how long no new turn may start
+    cache_ttl_seconds = 300   # the provider's prompt-cache lifetime, which the delay is a fraction of
+    min_messages = 3          # a conversation worth summarising
+    min_since_recap = 2       # and worth summarising again
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+from zettcode.app.commands import CommandContext, CommandResult
+from zettcode.app.plugins import HOST_LINK, HostLink, TuiPlugin
+from zettcode.engine.plugins.context import PluginContext
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Mapping
+    from typing import Any
+
+    from zettcode.app.commands import CommandHost
+
+#: The one place the version is written; ``pyproject.toml`` reads it from here.
+__version__ = "0.1.0"
+
+__all__ = ["RecapPlugin", "__version__"]
+
+#: What the model reads. Short by design: a recap is a line to get back to work with, not a summary of the work.
+PROMPT = (
+    "The user stepped away and is coming back. Recap in under 40 words, 1-2 plain sentences, no markdown. "
+    "Lead with the overall goal and current task, then the one next action. Skip root-cause narrative, fix "
+    "internals, secondary to-dos, and em-dash tangents."
+)
+
+#: How long one recap may take before it is dropped; one that arrives after the reader is working again is noise.
+TIMEOUT_SECONDS = 60.0
+
+#: The defaults, which a ``[plugins.recap]`` table overrides. See the module docstring for what they mean.
+DEFAULTS: dict[str, object] = {
+    "after_seconds": 180,
+    "cache_ttl_seconds": 300,
+    "min_messages": 3,
+    "min_since_recap": 2,
+}
+
+#: What a recap line starts with: the label inside the quote the message renderer draws.
+PREFIX = "Recap"
+
+#: The character a working row trails off with (the transcript's own ellipsis).
+ELLIPSIS = "\u2026"
+
+
+def quote(text: str) -> str:
+    """Return the recap as a Markdown blockquote, one marker per line so a wrapped answer stays inside it."""
+    return "\n".join(
+        f"> **{PREFIX}** \u00b7 {line}" if at == 0 else f"> {line}" for at, line in enumerate(text.split("\n"))
+    )
+
+
+def _number(given: Mapping[str, object], key: str, *, least: float) -> float:
+    """Return one declared setting as a number, refusing one that could never be meant."""
+    value = float(given[key])  # type: ignore[arg-type]  # `declare` checked it against the default's type
+    if value < least:
+        raise ValueError(f"[plugins.recap] {key} must be at least {least:g}, not {value:g}")
+    return value
+
+
+class RecapPlugin(TuiPlugin):
+    """Summarise the session when the reader has been away, and on ``/recap``."""
+
+    name = "recap"
+    description = "summarise where the session is when you step away"
+
+    def __init__(self) -> None:
+        """Start with nothing counted and no recap on its way."""
+        self._link: HostLink | None = None
+        #: Bumped by every turn start: a wait armed for an older one is for a conversation that has moved on.
+        self._generation = 0
+        self._turns = 0
+        self._since_recap = 0
+        self._seeded = False
+        self._session = ""
+        self._timer: asyncio.Task[None] | None = None
+        self._asking: asyncio.Task[None] | None = None
+        self.after_seconds = 180.0
+        self.cache_ttl_seconds = 300.0
+        self.min_messages = 3
+        self.min_since_recap = 2
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Read the settings, take the shell link, and register the command and the two hooks."""
+        given = ctx.settings.declare(**DEFAULTS)
+        self.after_seconds = _number(given, "after_seconds", least=0)
+        self.cache_ttl_seconds = _number(given, "cache_ttl_seconds", least=0)
+        self.min_messages = int(_number(given, "min_messages", least=1))
+        self.min_since_recap = int(_number(given, "min_since_recap", least=1))
+        self._link = ctx.find(HOST_LINK, HostLink)
+        if ctx.tui is None:
+            return
+        # `/recap` asks the shell's own side question, which takes seconds, so it returns the work to do and the shell
+        # shows what it is doing until it is answered; Ctrl-C and Escape stop it.
+        ctx.tui.register_command("recap", "summarise where this session is", self.command, when_busy="refuse")
+        ctx.tui.register_turn_start_handler(self.turn_started)
+        ctx.tui.register_turn_end_handler(self.turn_ended)
+
+    # -- the delay ---------------------------------------------------------------------------------
+    @property
+    def delay(self) -> float:
+        """Return how long the conversation must be quiet — no new turn — before a recap is made."""
+        return min(self.after_seconds, 0.8 * self.cache_ttl_seconds)
+
+    def due(self) -> bool:
+        """Return whether the conversation is long enough, and fresh enough, to be worth a recap."""
+        return self._turns >= self.min_messages and self._since_recap >= self.min_since_recap
+
+    # -- what the shell reports --------------------------------------------------------------------
+    def turn_started(self) -> None:
+        """The reader is asking again: whatever recap was waiting or being written is about a conversation that
+        has moved on, so it stops here."""
+        self._generation += 1
+        self._cancel()
+
+    def turn_ended(self, completed: bool) -> None:
+        """Count the turn, and start the idle wait.
+
+        Called on the shell's event loop: the counting happens here, and only what has to wait — the stored history,
+        the clock, the model — becomes a task.
+        """
+        host = self._host()
+        if host is None:
+            return
+        # The counts describe the conversation, not the plugin: `/new` or another session leaves them behind.
+        if host.client.session.id != self._session:
+            self._session = host.client.session.id
+            self._turns = 0
+            self._since_recap = 0
+            self._seeded = False
+            self._cancel()
+        self._turns += 1
+        self._since_recap += 1
+        if not self._seeded:
+            self._seeded = True
+            self._spawn(self._seed())
+        if self.due():
+            self._schedule()
+
+    def _schedule(self) -> None:
+        """Wait :attr:`delay` seconds, then recap if no turn has started since."""
+        if self._timer is not None and not self._timer.done():
+            return
+        self._timer = self._spawn(self._wait_then_recap(self._generation))
+
+    def _cancel(self) -> None:
+        """Drop a waiting recap and stop one being written: a turn started or the session changed, so the wait and
+        any recap are about a conversation that has moved on."""
+        for task in (self._timer, self._asking):
+            if task is not None and not task.done():
+                task.cancel()
+        self._timer = None
+        self._asking = None
+
+    async def _wait_then_recap(self, generation: int) -> None:
+        """Sleep for the delay, then make the recap nobody asked for."""
+        try:
+            await asyncio.sleep(self.delay)
+        except asyncio.CancelledError:
+            return
+        if generation != self._generation or not self.due():
+            return
+        with suppress(Exception):  # the timer has no reader to tell; the next turn may try again
+            text = await self._recap(cancellable=True)
+            if text:
+                self._show(text)
+
+    # -- the summary -------------------------------------------------------------------------------
+    async def _seed(self) -> None:
+        """Count what a resumed conversation already had, so ``min_messages`` means the session and not this run."""
+        host = self._host()
+        if host is None:
+            return
+        session = host.client.session.id
+        typed = 0
+        with suppress(Exception):  # a session another process holds, or a store that cannot be read
+            history = await host.client.session.history()
+            typed = sum(1 for message in history if message.role == "user" and message.relay is None)
+        if session != host.client.session.id or session != self._session:
+            return  # the reader left that conversation while its history was being read
+        self._turns = max(self._turns, typed)
+        # A resumed conversation can be worth a recap from its first new turn: the turn end that started this read
+        # saw too few messages to arm anything, so it is armed here, once the stored ones are counted.
+        if self.due() and (self._timer is None or self._timer.done()):
+            self._schedule()
+
+    async def _ask(self) -> str:
+        """Ask the model for the summary, as the shell's own side question.
+
+        Raises:
+            RuntimeError: The shell is not built yet.
+            Exception: Whatever the ask raised — a run already going, the session locked, the provider failing.
+        """
+        host = self._host()
+        if host is None:
+            raise RuntimeError("The shell is not ready yet")
+        return await host.client.session.ask(PROMPT, cache="read", timeout=TIMEOUT_SECONDS)
+
+    async def _recap(self, *, cancellable: bool) -> str:
+        """Ask for the summary and return it, saying nothing itself.
+
+        Args:
+            cancellable: Whether a new turn may stop it. True for the recap nobody asked for, which would be news
+                about a conversation that has moved on; false for ``/recap``, which was asked for and is answered
+                whatever the conversation does next.
+
+        Raises:
+            Exception: What the session's ``ask`` raised — refused because a run is going, the session locked by
+                another process, the provider failing — for a caller with a reader to tell.
+        """
+        if self._host() is None:
+            return ""
+        asking = asyncio.current_task() if cancellable else None
+        if cancellable:
+            self._asking = asking
+        try:
+            answer = await self._ask()
+        finally:
+            if cancellable and self._asking is asking:
+                self._asking = None
+        text = " ".join(answer.split()).strip()
+        if text:
+            self._since_recap = 0
+        return text
+
+    async def command(self, context: CommandContext) -> CommandResult:
+        """``/recap``: summarise now, whatever the clock and the turn count say.
+
+        The answer takes a model call, so the handler hands the waiting to the shell: the pinned row says what is
+        happening, and the reader can stop it while it works.
+        """
+        if self._host() is None:
+            raise ValueError("The shell is not ready yet; try again in a moment")
+        return CommandResult(intro=f"{PREFIX} {ELLIPSIS} writing", run=self._write())
+
+    async def _write(self) -> CommandResult:
+        """Ask for the summary and answer with it, as the rest of ``/recap``."""
+        try:
+            text = await self._recap(cancellable=False)
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            raise ValueError(f"Could not write a recap: {error}") from error
+        if not text:
+            return CommandResult(notification="Nothing to recap yet")
+        return CommandResult(message=quote(text), notification=f"{PREFIX} ready")
+
+    # -- helpers -----------------------------------------------------------------------------------
+    def _show(self, text: str) -> None:
+        """Say it in the conversation as a message — the row a command's answer uses — and ask for the frame."""
+        host = self._host()
+        if host is None:
+            return
+        host.transcript.markdown(quote(text))
+        # A recap arrives between keys, so nothing else would ask for the frame that shows it.
+        host.request_layout()
+
+    def _host(self) -> CommandHost | None:
+        """Return the shell, or ``None`` before it is built (and in a program that has none)."""
+        return self._link.host if self._link is not None else None
+
+    @staticmethod
+    def _spawn(coroutine: Coroutine[Any, Any, None]) -> asyncio.Task[None]:
+        """Run one piece of waiting work as a task on the loop the shell already runs on."""
+        task = asyncio.get_running_loop().create_task(coroutine)
+        task.add_done_callback(RecapPlugin._swallow)
+        return task
+
+    @staticmethod
+    def _swallow(task: asyncio.Task[None]) -> None:
+        """A background failure is the plugin's own business: the shell keeps running, and a later turn may retry."""
+        with suppress(asyncio.CancelledError, Exception):
+            task.exception()

zettcode_recap-0.1.0/tests/test_recap.py

@@ -0,0 +1,357 @@
+"""The recap plugin, driven by the shell's two hooks and its own command."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+from zettcode.app.commands import CommandContext
+from zettcode.app.plugins import HOST_LINK, HostLink
+from zettcode.app.plugins.loader import terminal_context
+from zettcode.config import ModelConfig, ZettCodeConfig
+
+from zettcode_recap import PROMPT, RecapPlugin
+
+SESSION = "s-1"
+
+
+class FakeSession:
+    """What the shell's SDK client offers a recap: one side question, or a refusal."""
+
+    def __init__(self, answer: str = "Fixing the parser; next, run the tests.") -> None:
+        self.id = SESSION
+        self.answer = answer
+        self.asked: list[tuple[str, float | None, str]] = []
+        self.locked = False
+        self.refuse: Exception | None = None
+        #: When set, ``ask`` waits for it, so a test can hold a recap in flight.
+        self.gate: asyncio.Event | None = None
+        #: When set, ``history`` waits for it, so a test can leave a seed reading while the session changes.
+        self.history_gate: asyncio.Event | None = None
+        self.history_messages: list[object] = []
+
+    async def ask(self, question: str, *, on_event=None, timeout=None, cache="read") -> str:
+        self.asked.append((question, timeout, cache))
+        if self.gate is not None:
+            await self.gate.wait()
+        if self.refuse is not None:
+            raise self.refuse
+        return self.answer
+
+    async def history(self):
+        # The conversation is the one that was asked for when the call was made, even if the shell has moved on by
+        # the time the store answers; only the one the test filled in has messages.
+        asked_for = self.id
+        if self.history_gate is not None:
+            await self.history_gate.wait()
+        return self.history_messages if asked_for == SESSION else []
+
+
+class FakeTranscript:
+    def __init__(self) -> None:
+        self.notices: list[str] = []
+        self.messages: list[str] = []
+
+    def notice(self, text: str) -> None:
+        self.notices.append(text)
+
+    def markdown(self, text: str) -> None:
+        self.messages.append(text)
+
+
+class FakeUi:
+    def markdown(self, text: str) -> None: ...
+
+    def notice(self, text: str) -> None: ...
+
+    def error(self, text: str) -> None: ...
+
+    def notify(self, text: str, *, level: str = "info") -> None: ...
+
+
+class FakeHost:
+    def __init__(self, session: FakeSession | None = None) -> None:
+        self.client = type("Client", (), {"session": session or FakeSession()})()
+        self.transcript = FakeTranscript()
+        self.redraws = 0
+
+    def request_layout(self) -> None:
+        self.redraws += 1
+
+
+def build(tmp_path: Path, settings: dict[str, object] | None = None, host: FakeHost | None = None):
+    """Activate the plugin against a config, with a shell attached when the test wants one."""
+    config = ZettCodeConfig(
+        workspace=tmp_path,
+        models=(ModelConfig(model="m", token="t"),),
+        plugin_settings={"recap": settings or {}},
+    )
+    link = HostLink()
+    ctx = terminal_context(config, {HOST_LINK: link}, name="recap")
+    plugin = RecapPlugin()
+    plugin.activate(ctx)
+    if host is not None:
+        link.attach(host)  # type: ignore[arg-type]
+    return plugin, ctx, link
+
+
+async def settled(predicate, *, ticks: int = 200) -> None:
+    """Let the plugin's background tasks run until the condition holds, or fail the test."""
+    for _ in range(ticks):
+        if predicate():
+            return
+        await asyncio.sleep(0)
+    raise AssertionError("the plugin did not get where the test waited for")
+
+
+async def test_coming_back_does_not_cancel_a_recap_the_reader_asked_for(tmp_path):
+    """/recap is answered whatever the window does; only the unsolicited one is dropped when the reader returns."""
+    session = FakeSession()
+    session.gate = asyncio.Event()
+    plugin, ctx, _link = build(tmp_path, {"after_seconds": 0}, host=FakeHost(session))
+    (command,) = ctx.tui.registered_commands
+
+    pending = await command.handler(CommandContext(argument="", ui=FakeUi()))
+    asked = asyncio.ensure_future(pending.run)
+    await settled(lambda: bool(session.asked))
+    plugin.turn_started()
+    session.gate.set()
+    result = await asyncio.wait_for(asked, 1.0)
+
+    assert result.notification == "Recap ready", "the command finished instead of being cancelled"
+    plugin._cancel()
+
+
+async def test_the_unsolicited_recap_is_dropped_when_a_turn_starts(tmp_path):
+    session = FakeSession()
+    session.gate = asyncio.Event()
+    plugin, _ctx, _link = build(tmp_path, {"after_seconds": 0}, host=FakeHost(session))
+    host = plugin._host()
+    assert host is not None
+
+    for _ in range(3):
+        plugin.turn_ended(True)
+    await settled(lambda: bool(session.asked))
+    plugin.turn_started()
+    session.gate.set()
+    await asyncio.sleep(0)
+    await asyncio.sleep(0)
+
+    assert host.transcript.messages == [], "nothing is shown for a conversation that has moved on"
+
+
+async def test_a_command_does_not_forget_the_automatic_recap_that_is_running(tmp_path):
+    """Only the unsolicited recap is cancellable, so `/recap` must not take over — or drop — its handle."""
+    session = FakeSession()
+    session.gate = asyncio.Event()
+    plugin, ctx, _link = build(tmp_path, host=FakeHost(session))
+    (command,) = ctx.tui.registered_commands
+    automatic = asyncio.ensure_future(asyncio.sleep(3600))
+    plugin._asking = automatic
+
+    pending = await command.handler(CommandContext(argument="", ui=FakeUi()))
+    asked = asyncio.ensure_future(pending.run)
+    await settled(lambda: bool(session.asked))
+    assert plugin._asking is automatic, "the automatic recap can still be cancelled while a command's runs"
+
+    session.gate.set()
+    await asyncio.wait_for(asked, 1.0)
+    automatic.cancel()
+    plugin._cancel()
+
+
+async def test_a_seed_read_before_a_session_change_does_not_count_for_the_new_one(tmp_path):
+    """The reader can leave a conversation while its history is being read; those messages are not the new one's."""
+    session = FakeSession()
+    session.history_gate = asyncio.Event()
+    session.history_messages = [type("Message", (), {"role": "user", "relay": None})()] * 10
+    plugin, _ctx, _link = build(tmp_path, host=FakeHost(session))
+
+    plugin.turn_ended(True)
+    await asyncio.sleep(0)  # let the first seed ask the store, which is where it will be held
+    session.id = "s-2"
+    plugin.turn_ended(True)
+    session.history_gate.set()
+    await asyncio.sleep(0)
+    await asyncio.sleep(0)
+
+    assert plugin._turns == 1, "the old conversation's ten messages were dropped"
+    plugin._cancel()
+
+
+async def test_a_new_session_starts_its_own_count(tmp_path):
+    """`/new` is a new conversation: the old one's three messages must not make the new one worth a recap."""
+    session = FakeSession()
+    plugin, _ctx, _link = build(tmp_path, host=FakeHost(session))
+
+    for _ in range(3):
+        plugin.turn_ended(True)
+    assert plugin._turns == 3
+
+    session.id = "s-2"
+    plugin.turn_ended(True)
+
+    assert plugin._turns == 1
+    assert plugin.due() is False
+    plugin._cancel()
+
+
+async def test_a_resumed_conversation_is_measured_by_its_stored_messages(tmp_path):
+    """One new turn in a long session can be worth a recap the moment the history is read, even if nobody looks away again."""
+    session = FakeSession()
+    session.history_messages = [
+        type("Message", (), {"role": "user", "relay": None})(),
+        type("Message", (), {"role": "assistant", "relay": None})(),
+    ] * 10
+    plugin, _ctx, _link = build(tmp_path, {"after_seconds": 0, "min_since_recap": 1}, host=FakeHost(session))
+
+    plugin.turn_ended(True)
+    await settled(lambda: bool(session.asked))
+
+    assert plugin._turns == 10, "the stored user messages count"
+    assert session.asked, "and the recap that count makes worthwhile was written"
+    plugin._cancel()
+
+
+def test_the_command_is_offered_and_both_hooks_are_taken(tmp_path):
+    """`/recap` says words, so it is a plain command; the two hooks are the terminal's."""
+    _plugin, ctx, _link = build(tmp_path)
+
+    assert ctx.tui is not None
+    assert [command.name for command in ctx.tui.registered_commands] == ["/recap"]
+    assert ctx.commands.commands == ()
+    assert ctx.tui.focus_handlers == (), "the wait is about turns, not the window"
+    assert len(ctx.tui.turn_start_handlers) == 1 and len(ctx.tui.turn_end_handlers) == 1
+
+
+def test_the_delay_is_the_shorter_of_its_own_seconds_and_the_cache_lifetime(tmp_path):
+    plugin, _ctx, _link = build(tmp_path)
+
+    assert plugin.delay == 180, "min(180, 0.8 × 300)"
+
+    plugin.cache_ttl_seconds = 100
+    assert plugin.delay == 80, "a short-lived cache is not worth waiting longer for"
+
+
+async def test_a_conversation_that_is_too_short_arms_no_wait(tmp_path):
+    session = FakeSession()
+    plugin, _ctx, _link = build(tmp_path, host=FakeHost(session))
+
+    for _ in range(2):
+        plugin.turn_ended(True)
+    await asyncio.sleep(0)
+
+    assert plugin._timer is None and session.asked == []
+    plugin._cancel()
+
+
+async def test_a_reader_who_stayed_away_long_enough_gets_a_recap(tmp_path):
+    session = FakeSession()
+    plugin, _ctx, _link = build(tmp_path, {"after_seconds": 0}, host=FakeHost(session))
+    host = plugin._host()
+    assert host is not None
+
+    for _ in range(3):
+        plugin.turn_ended(True)
+    await settled(lambda: bool(session.asked))
+
+    assert session.asked == [(PROMPT, 60.0, "read")], "one side question, read-only, with a deadline"
+    assert host.transcript.messages == ["> **Recap** \u00b7 Fixing the parser; next, run the tests."]
+    assert host.redraws == 1, "the frame that shows it is asked for"
+    plugin._cancel()
+
+
+async def test_a_new_turn_drops_the_recap_that_was_waiting(tmp_path):
+    """The reader asking again is the one thing that makes a recap about the past: it is dropped, not shown late."""
+    session = FakeSession()
+    plugin, _ctx, _link = build(tmp_path, host=FakeHost(session))
+
+    for _ in range(3):
+        plugin.turn_ended(True)
+    assert plugin._timer is not None
+    plugin.turn_started()
+    await settled(lambda: plugin._timer is None)
+
+    assert session.asked == []
+    plugin._cancel()
+
+
+async def test_two_recaps_are_not_made_from_the_same_two_turns(tmp_path):
+    plugin, _ctx, _link = build(tmp_path, host=FakeHost())
+    plugin._focused = False
+
+    for _ in range(3):
+        plugin.turn_ended(True)
+    plugin._schedule()
+    plugin._since_recap = 0  # as if a recap had just been made
+
+    assert plugin.due() is False, "two more turns are needed before the next one"
+    plugin._cancel()
+
+
+async def test_the_command_summarises_now_and_shows_the_answer(tmp_path):
+    session = FakeSession()
+    plugin, ctx, _link = build(tmp_path, host=FakeHost(session))
+    (command,) = ctx.tui.registered_commands
+
+    pending = await command.handler(CommandContext(argument="", ui=FakeUi()))
+    result = await pending.run
+
+    assert result.notification == "Recap ready"
+    assert result.message == "> **Recap** \u00b7 Fixing the parser; next, run the tests.", "words are the answer"
+    assert session.asked[0][2] == "read"
+
+
+async def test_the_command_tells_the_reader_why_there_is_no_recap(tmp_path):
+    session = FakeSession()
+    session.refuse = RuntimeError("the provider refused")
+    plugin, ctx, _link = build(tmp_path, host=FakeHost(session))
+    (command,) = ctx.tui.registered_commands
+
+    pending = await command.handler(CommandContext(argument="", ui=FakeUi()))
+    with pytest.raises(ValueError, match="Could not write a recap: the provider refused"):
+        await pending.run
+
+
+async def test_a_command_before_the_shell_exists_says_so_instead_of_crashing(tmp_path):
+    _plugin, ctx, _link = build(tmp_path)
+    (command,) = ctx.tui.registered_commands
+
+    with pytest.raises(ValueError, match="not ready yet"):
+        await command.handler(CommandContext(argument="", ui=FakeUi()))
+
+
+async def test_the_settings_of_the_table_are_the_ones_the_recap_uses(tmp_path):
+    plugin, _ctx, _link = build(
+        tmp_path,
+        {"after_seconds": 30, "cache_ttl_seconds": 600, "min_messages": 5, "min_since_recap": 1},
+        host=FakeHost(),
+    )
+
+    assert plugin.after_seconds == 30 and plugin.cache_ttl_seconds == 600
+    assert plugin.delay == 30, "min(30, 480)"
+    assert (plugin.min_messages, plugin.min_since_recap) == (5, 1)
+
+    for _ in range(4):
+        plugin.turn_ended(True)
+    assert plugin.due() is False, "the table asked for five messages"
+    plugin.turn_ended(True)
+    assert plugin.due() is True
+    plugin._cancel()
+
+
+def test_a_setting_that_could_never_be_meant_is_refused_when_the_plugin_activates(tmp_path):
+    with pytest.raises(ValueError, match=r"\[plugins\.recap\] after_seconds must be at least 0"):
+        build(tmp_path, {"after_seconds": -1})
+
+
+def test_the_plugin_also_activates_without_a_screen(tmp_path):
+    """Every process loads every plugin; one that only draws into a terminal must leave the others alone."""
+    config = ZettCodeConfig(workspace=tmp_path, models=(ModelConfig(model="m", token="t"),))
+    from zettcode.engine.plugins.context import PluginContext
+
+    plugin = RecapPlugin()
+    plugin.activate(PluginContext(config, {}))
+
+    assert plugin._link is None