zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/__init__.py

@@ -0,0 +1,63 @@
+"""ZettCode's application layer, split into its interface and its agent glue.
+
+``ui`` holds what the user sees and drives: the transcript and the application
+shell. ``agent`` holds the adapter that turns agent events into transcript
+entries. This module is the facade over both, so ``from zettcode.app import
+ZettCodeApp`` keeps working for callers that do not care where it lives.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "Entry": ".agent",
+    "Transcript": ".agent",
+    "TranscriptProjector": ".agent",
+    "TranscriptSource": ".ui",
+    "TranscriptView": ".ui",
+    "TerminalAgent": ".agent",
+    "ZettCodeApp": ".ui",
+    "ZettCodeRoot": ".ui",
+    "ZettCodeEngine": ".agent",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from .agent import Entry, TerminalAgent, Transcript, TranscriptProjector, ZettCodeEngine
+    from .ui import TranscriptSource, TranscriptView, ZettCodeApp, ZettCodeRoot
+
+
+def __getattr__(name: str) -> object:
+    """Import the module a public name lives in, the first time it is asked for.
+
+    This package is a facade over several subpackages, and a caller that wants
+    one name should not pay for the rest of them — the TUI alone holds the
+    widget library, the Markdown parser, the diff viewer, and the syntax
+    scanners. ``__all__`` is still the public surface.
+    """
+    try:
+        module = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(importlib.import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """Return the names this package publishes."""
+    return sorted(__all__)
+
+
+__all__ = [
+    "Entry",
+    "Transcript",
+    "TranscriptProjector",
+    "TranscriptSource",
+    "TranscriptView",
+    "ZettCodeApp",
+    "TerminalAgent",
+    "ZettCodeRoot",
+    "ZettCodeEngine",
+]

zettcode/app/agent/__init__.py

@@ -0,0 +1,47 @@
+"""Agent-facing glue: the conversation model and the events that fill it."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "Entry": "zettcode.plugin_api.entries",
+    "Transcript": ".conversation.transcript",
+    "TranscriptProjector": ".conversation.projection",
+    "TerminalAgent": ".agent",
+    "ZettCodeEngine": "zettcode.engine.core",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from zettcode.engine.core import ZettCodeEngine
+    from zettcode.plugin_api.entries import Entry
+
+    from .agent import TerminalAgent
+    from .conversation.projection import TranscriptProjector
+    from .conversation.transcript import Transcript
+
+
+def __getattr__(name: str) -> object:
+    """Import the module a public name lives in, the first time it is asked for.
+
+    This package is a facade over several subpackages, and a caller that wants
+    one name should not pay for the rest of them — the TUI alone holds the
+    widget library, the Markdown parser, the diff viewer, and the syntax
+    scanners. ``__all__`` is still the public surface.
+    """
+    try:
+        module = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(importlib.import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """Return the names this package publishes."""
+    return sorted(__all__)
+
+
+__all__ = ["Entry", "Transcript", "TranscriptProjector", "TerminalAgent", "ZettCodeEngine"]

zettcode/app/agent/agent/__init__.py

@@ -0,0 +1,84 @@
+"""The terminal's agent: the engine's agent, plus the commands and preferences only a terminal has.
+
+The engine's agent (:class:`zettcode.engine.agent.ZettCodeAgent`) does the work. This subclass adds what the shell
+asks of it that is not work: the slash commands and what plugins contributed (``commands``), and the theme, the pet
+and the status line the reader can change (``settings``). Its engine is built with the terminal's plugin loader, so
+the commands, palettes, pets, presenters and rows of the plugins are there to be read.
+
+This package is also where the terminal is put together from the engine's parts, so it is what names, for the views, the
+engine objects they hold: ``SessionLink`` (the line to the other sessions) and ``StoredSession`` (a session read from
+the store). The views import those names from here and not from the engine.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeAlias
+
+from zettcode.engine.agent import ZettCodeAgent
+from zettcode.engine.agent.sessions import StoredSession
+from zettcode.engine.core import PluginLoader, ZettCodeEngine
+from zettcode.messaging.messenger import SESSION_LINK, Messenger
+from zettcode.plugin_api.commands import CommandAgent
+
+from .commands import CommandsMixin
+
+#: The line to the other sessions, under the name the views use for it.
+SessionLink: TypeAlias = Messenger
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Mapping
+
+    from zettcode.config import ZettCodeConfig
+    from zettcode.sdk.client import Client
+
+__all__ = ["SessionLink", "StoredSession", "TerminalAgent"]
+
+
+def _terminal_loader() -> PluginLoader:
+    """Return the terminal's plugin loader, imported when an agent is built and not before."""
+    from zettcode.app.plugins.loader import terminal_plugins
+
+    return terminal_plugins
+
+
+# The contract is last on purpose: `AgentBase`'s concrete `session_id`/`workspace` must win over `CommandAgent`'s
+# abstract properties, or the class becomes uninstantiable.
+class TerminalAgent(CommandsMixin, ZettCodeAgent, CommandAgent):
+    """The agent the terminal application drives."""
+
+    _client: Client | None = None
+
+    @property
+    def messenger(self) -> SessionLink | None:
+        """Return the line to the other sessions, or ``None`` when the configuration switches messaging off."""
+        bundle = getattr(self.runtime, "plugins", None)
+        return None if bundle is None else bundle.find(SESSION_LINK, SessionLink)
+
+    @property
+    def client(self) -> Client:
+        """Return the SDK client over this agent, which is how the shell reaches everything the SDK offers.
+
+        Made on first use and then kept, so the shell and the commands it runs read the same client. The agent still
+        owns closing: the client is a view of it.
+        """
+        if self._client is None:
+            from zettcode.sdk.client import Client
+
+            self._client = Client._around(self)
+        return self._client
+
+    @classmethod
+    async def create(cls, config: ZettCodeConfig, load: PluginLoader | None = None) -> TerminalAgent:
+        """Build the engine with the terminal's plugins and start it."""
+        return cls(await ZettCodeEngine.create(config, load or _terminal_loader()))
+
+    @classmethod
+    def preview(
+        cls,
+        config: ZettCodeConfig,
+        load: PluginLoader | None = None,
+        *,
+        shared: Mapping[str, object] | None = None,
+    ) -> TerminalAgent:
+        """Wrap an engine that still has to start, built with the terminal's plugins, so the shell can paint first."""
+        return cls(ZettCodeEngine.preview(config, load or _terminal_loader(), shared=shared))

zettcode/app/agent/agent/commands.py

@@ -0,0 +1,269 @@
+"""What the agent offers the shell to run and to show: its own commands, and what plugins added.
+
+The commands report through transcript Markdown; commands that present a widget belong to
+the shell, which owns the widgets. The plugin contributions are listed here because the
+agent is where the shell asks for everything the runtime loaded.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+from zettcode.engine.agent.exports import ExportsMixin
+from zettcode.plugin_api.commands import Command, CommandContext, CommandHost, CommandResult
+from zettcode.plugin_api.host import HOST_LINK, HostLink
+from zettcode.plugin_api.pets import PetCatalog
+from zettcode.plugin_api.plugin import TuiPlugins
+from zettcode.plugin_api.presenters import Presenters
+from zettcode.plugin_api.state import TurnSegment, UiRow
+from zettcode.presenters.statusline import NAMES, unknown
+from zettcode.providers import BUILTIN_PROVIDERS, Provider, merge_providers
+from zettcode.tui import ThemeCatalog
+
+from .settings import AppearanceMixin
+
+#: The words ``/self-compact`` takes after it, or after ``global``.
+_SELF_COMPACT_WORDS = frozenset({"on", "off", "default"})
+
+
+class CommandsMixin(AppearanceMixin, ExportsMixin):
+    """The ``/new``, ``/compact``, and ``/export`` commands, and the plugins' commands, mentions, and rows."""
+
+    @property
+    def terminal_plugins(self) -> TuiPlugins:
+        """Return what the plugins contributed to the terminal; the engine was built with the terminal's loader."""
+        plugins = self.runtime.plugins
+        if not isinstance(plugins, TuiPlugins):
+            raise TypeError("This agent's engine was not built with the terminal's plugin loader")
+        return plugins
+
+    @property
+    def commands(self) -> tuple[Command, ...]:
+        """Return the conversation commands the agent owns.
+
+        They report through transcript Markdown; commands that present a widget
+        (such as the model picker) belong to the shell, which owns the widgets.
+        """
+        return (
+            Command("/new", "start a fresh session", "agent", self._command_new),
+            Command("/compact", "summarize the context now", "agent", self._command_compact),
+            Command("/export", "write this session to an HTML file: /export [path]", "agent", self._command_export),
+        )
+
+    def attach_host(self, host: CommandHost) -> None:
+        """Tell the plugins where the shell is, so the words their commands offer can follow the session."""
+        link = self.runtime.plugins.find(HOST_LINK, HostLink)
+        if link is not None:
+            link.attach(host)
+
+    @property
+    def plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the installed plugins registered, not counting the built-in ones.
+
+        The shell keeps them after everything built in, so a plugin cannot take over a built-in name;
+        plugin-versus-plugin duplicates are rejected when the plugins load.
+        """
+        return self.terminal_plugins.installed_commands
+
+    @property
+    def builtin_plugin_commands(self) -> tuple[Command, ...]:
+        """Return the commands the program's own plugins registered: ``/resume``, ``/model``, ``/usage`` and the rest."""
+        return self.terminal_plugins.builtin_commands
+
+    @property
+    def providers(self) -> tuple[Provider, ...]:
+        """Return the hosts ``/config`` can offer: the built-in ones, then the plugins' own."""
+        return merge_providers(BUILTIN_PROVIDERS, self.runtime.plugins.providers)
+
+    @property
+    def themes(self) -> ThemeCatalog:
+        """Return every palette that can be asked for by name: the plugins', then the reader's own files.
+
+        Built fresh each time it is asked: it lists names and builds nothing, and the reader's directory may have
+        gained a file since the last look.
+        """
+        return ThemeCatalog(self.terminal_plugins.themes, self.runtime.config.themes_dir)
+
+    @property
+    def pets(self) -> PetCatalog:
+        """Return every pet that can be asked for by name, in the order the plugins registered them.
+
+        Nothing is bundled here: with no pets plugin the catalog is empty.
+        """
+        return PetCatalog(self.terminal_plugins.pets)
+
+    @property
+    def turn_segments(self) -> tuple[TurnSegment, ...]:
+        """Return the items of the line a request ends on, the program's own first, then the plugins'."""
+        return self.terminal_plugins.turn_segments
+
+    @property
+    def pets_switched_off(self) -> bool:
+        """Return whether the reader turned the pets plugin off, which is why a catalog of none is empty."""
+        from zettcode.engine.plugins import off_names
+
+        return "pets" in off_names(self.runtime.config)
+
+    @property
+    def plugin_failures(self) -> tuple[str, ...]:
+        """Return one message per plugin that could not be loaded or activated."""
+        return self.terminal_plugins.failures
+
+    @property
+    def presenters(self) -> Presenters:
+        """Return how this run draws entries: the built-in presenters, and any a plugin outranks them with.
+
+        Built from the bundle rather than from a module-level default for the same reason the palettes are: the
+        program's own rows are registered through the plugin route, so a plugin that draws a kind or a family of
+        rows reaches the transcript without a second path only plugins could not take.
+        """
+        return Presenters(self.terminal_plugins.presenters)
+
+    @property
+    def plugin_rows(self) -> tuple[UiRow, ...]:
+        """Return the header and status rows plugins asked the shell to draw."""
+        return self.terminal_plugins.rows
+
+    @property
+    def plugin_focus_handlers(self) -> tuple[Callable[[bool], None], ...]:
+        """Return the handlers told when the terminal window gains or loses focus."""
+        return self.terminal_plugins.focus_handlers
+
+    @property
+    def plugin_turn_start_handlers(self) -> tuple[Callable[[], None], ...]:
+        """Return the handlers told when a turn of the conversation starts."""
+        return self.terminal_plugins.turn_start_handlers
+
+    @property
+    def plugin_turn_end_handlers(self) -> tuple[Callable[[bool], None], ...]:
+        """Return the handlers told when a turn of the conversation ends."""
+        return self.terminal_plugins.turn_end_handlers
+
+    async def _command_new(self, context: CommandContext) -> CommandResult:
+        """Start a fresh session."""
+        session_id = self.new_session()
+        return CommandResult(notification=f"started session {session_id[:8]}")
+
+    async def _command_export(self, context: CommandContext) -> CommandResult:
+        """Write the session and its context to one HTML file.
+
+        The path argument is optional; without it the file lands in the
+        workspace, named after the session, and the result says where.
+        """
+        path = await self.export_session(context.argument.strip() or None)
+        return CommandResult(message=f"Exported to `{path}`")
+
+    def self_compaction_summary(self) -> str:
+        """Say in one line whether self-compaction is on here, where that comes from, and what the default is."""
+        state = "on" if self.self_compaction else "off"
+        default = "on" if self.self_compaction_default else "off"
+        if self.self_compaction_choice is None:
+            return f"Self-compaction is {state}: this session follows the default ({default})"
+        return f"Self-compaction is {state}: this session chose it; the default is {default}"
+
+    def self_compact_report(self) -> str:
+        """Say what self-compaction is, whether it is on here, and where that comes from."""
+        choice = self.self_compaction_choice
+        default = "on" if self.self_compaction_default else "off"
+        state = "on" if self.self_compaction else "off"
+        source = (
+            f"this session chose it; the config default is **{default}**"
+            if choice is not None
+            else "following the config default (`[compaction] self`)"
+        )
+        return (
+            f"Self-compaction is **{state}** ({source}).\n\n"
+            "When on, the model gets a `compact_context` tool and can summarize its own earlier conversation "
+            "when it judges the detail is no longer needed. The current turn is always kept. "
+            "`/compact` and the automatic threshold work either way.\n\n"
+            "`/self-compact on|off` sets this session; `default` hands it back to the config; "
+            "`global on|off` changes the default for every session that has not chosen."
+        )
+
+    def change_self_compaction(self, argument: str) -> str:
+        """Read or change self-compaction from the words ``/self-compact`` takes, and say what now applies.
+
+        ``on``, ``off`` and ``default`` set this session's own choice; ``global on`` and ``global off``
+        write the default for every session into the config file. A failed write is never reported as saved.
+
+        Raises:
+            ValueError: The words are not ones the command takes, or the change could not be saved.
+        """
+        words = argument.lower().split()
+        scope = "session"
+        if words[:1] == ["global"]:
+            scope, words = "global", words[1:]
+        usage = ValueError("Usage: /self-compact [on|off|default] or /self-compact global on|off")
+        if len(words) > 1 or (scope == "global" and not words) or (words and words[0] not in _SELF_COMPACT_WORDS):
+            raise usage
+        if scope == "global":
+            if words[0] == "default":
+                raise usage
+            self.remember_self_compaction(words[0] == "on")
+        elif words:
+            self.use_self_compaction({"on": True, "off": False, "default": None}[words[0]])
+        return self.self_compact_report()
+
+    def statusline_summary(self) -> str:
+        """Say in one line which parts of the header and the status line are hidden."""
+        hidden = [
+            *(name for name in NAMES if name in self.statusline_hidden),
+            *sorted(self.statusline_hidden - set(NAMES)),
+        ]
+        if not hidden:
+            return "Status line: every part is shown"
+        total = len(NAMES) + len({item.name for item in self.turn_segments} - set(NAMES))
+        return f"Status line: {len(hidden)} of {total} parts hidden ({', '.join(hidden)})"
+
+    def change_statusline(self, argument: str) -> str:
+        """Hide or show parts of the header and status line from the words ``/statusline`` takes.
+
+        ``hide <name>...`` and ``show <name>...`` change the named parts, and ``show all`` brings every one
+        back. The change is written to ``[statusline]`` in the config file, and nothing is changed when any
+        name is not a part.
+
+        Raises:
+            ValueError: The words are not ones the command takes, or the change could not be saved.
+        """
+        words = argument.lower().split()
+        usage = ValueError(
+            f"Usage: /statusline [hide|show] <part>... or /statusline show all; parts: {', '.join(NAMES)}"
+        )
+        if len(words) < 2 or words[0] not in {"hide", "show"}:
+            raise usage
+        visible = words[0] == "show"
+        names = list(NAMES) if visible and words[1:] == ["all"] else words[1:]
+        if stray := unknown(names):
+            raise ValueError(f"No such part: {', '.join(stray)}. Parts: {', '.join(NAMES)}")
+        self.remember_statusline({name: visible for name in names})
+        return self.statusline_summary()
+
+    async def _command_compact(self, context: CommandContext) -> CommandResult:
+        """Summarize the conversation now, whatever its size.
+
+        The row is opened only after the refusal check. That check may read a
+        cold session on a worker, so the interface stays live while it runs;
+        once the row is up, the shell draws it before the pass starts. What
+        follows the first ``await`` is still synchronous token counting and the
+        summary request, so a row created only by ``CompactionStarted`` would
+        reach the screen after the work it was meant to explain.
+        """
+        host = context.host
+        if host is not None:
+            await self.ensure_compactable()
+            host.transcript.start_compaction()
+        try:
+            if host is not None:
+                await host.wait_for_frame()
+                await self._compact_pass()
+            else:
+                await self.compact()
+        except asyncio.CancelledError:
+            if host is not None:
+                host.transcript.complete_compaction("Compacting stopped")
+            raise
+        finally:
+            if host is not None:
+                host.transcript.complete_compaction()
+        return CommandResult()

zettcode/app/agent/agent/settings.py

@@ -0,0 +1,132 @@
+"""What the reader can change about how the terminal looks: theme, pet, which parts of the status line are shown.
+
+These are the terminal's own preferences. They are kept in the same config file as the engine's settings, and are
+written the same way, which is why this reads the file through the engine's helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from zettcode.config_edit import (
+    ConfigEditError,
+    set_pet,
+    set_pet_position,
+    set_statusline,
+    set_theme,
+    write_text_atomically,
+)
+from zettcode.engine.agent.settings import SettingsMixin
+from zettcode.presenters.statusline import NAMES
+
+
+class AppearanceMixin(SettingsMixin):
+    """Read and remember the terminal's theme, pet and status line."""
+
+    @property
+    def reduced_motion(self) -> bool:
+        """Return whether decorative animation is disabled."""
+        return self.runtime.config.reduced_motion
+
+    def remember_theme(self, name: str) -> Path:
+        """Write ``[ui] theme = name`` into the config file, so the next start opens in that palette.
+
+        Only that line changes. A config file that does not exist is not created for it: a file with nothing but
+        ``[ui]`` in it would stand where a reader's environment-variable setup is, and say nothing about models.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot be
+                written. Nothing is written then.
+        """
+        text = set_theme(self._read_config_file(), name, where=self.config_file)
+        try:
+            write_text_atomically(self.config_file, text)
+        except OSError as error:
+            raise ConfigEditError(f"{self.config_file} could not be written: {error}") from error
+        return self.config_file
+
+    def remember_pet(self, name: str) -> Path:
+        """Write ``[ui] pet = name`` into the config file, so the next start opens with that pet.
+
+        Only that line changes, and a config file that does not exist is not created for it. The pet in force
+        for this run is the shell's to switch; what this keeps up to date is the setting the shell reads back.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot be
+                written. Nothing is written then.
+        """
+        text = set_pet(self._read_config_file(), name, where=self.config_file)
+        try:
+            write_text_atomically(self.config_file, text)
+        except OSError as error:
+            raise ConfigEditError(f"{self.config_file} could not be written: {error}") from error
+        self.runtime.config = replace(self.runtime.config, pet=name)
+        return self.config_file
+
+    def remember_pet_position(self, across: float, down: float) -> Path:
+        """Write ``[ui] pet_position`` into the config file, so the next start puts the pet back where it was left.
+
+        The file is global to the reader (``~/.zettcode/config.toml``), not to a project: a pet is the reader's
+        companion, and it does not move house when they open another folder. Only that line changes, and a
+        config file that does not exist is not created for it.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot be
+                written. Nothing is written then.
+        """
+        text = set_pet_position(self._read_config_file(), across, down, where=self.config_file)
+        try:
+            write_text_atomically(self.config_file, text)
+        except OSError as error:
+            raise ConfigEditError(f"{self.config_file} could not be written: {error}") from error
+        position = (round(min(1.0, max(0.0, across)), 3), round(min(1.0, max(0.0, down)), 3))
+        self.runtime.config = replace(self.runtime.config, pet_position=position)
+        return self.config_file
+
+    @property
+    def statusline_hidden(self) -> frozenset[str]:
+        """Return the names of the header and status-line parts the reader switched off."""
+        return frozenset(self.runtime.config.statusline_hidden)
+
+    def remember_statusline(self, shown: Mapping[str, bool]) -> Path:
+        """Write which parts of the header and status line are shown into ``[statusline]``.
+
+        Only the parts that differ from what is in force are written. The file is written first and the
+        running configuration changed second, so a write that fails leaves both as they were; the rows
+        follow at the next paint. A config file that does not exist is not created for it, as for the theme.
+
+        Args:
+            shown: Part name to whether it is shown. A part left out keeps what it has.
+
+        Returns:
+            The file written.
+
+        Raises:
+            ConfigEditError: When there is no config file, it cannot be read or edited safely, or it cannot
+                be written.
+        """
+        hidden = set(self.statusline_hidden)
+        changes = {name: visible for name, visible in shown.items() if (name not in hidden) != visible}
+        if not changes:
+            return self.config_file
+        text = set_statusline(self._read_config_file(), changes, where=self.config_file)
+        try:
+            write_text_atomically(self.config_file, text)
+        except OSError as error:
+            raise ConfigEditError(f"{self.config_file} could not be written: {error}") from error
+        hidden = {name for name in hidden if name not in changes} | {name for name, v in changes.items() if not v}
+        # The program's parts in their order, then the ones a plugin added (their names are not in NAMES).
+        ordered = (*(name for name in NAMES if name in hidden), *sorted(hidden - set(NAMES)))
+        self.runtime.config = replace(self.runtime.config, statusline_hidden=ordered)
+        return self.config_file

zettcode/app/agent/conversation/__init__.py

@@ -0,0 +1,7 @@
+"""The conversation as the screen shows it: entries, how they are drawn, and what fills them.
+
+``entries`` is the data, ``transcript`` the ordered list of it, ``presenters`` how one
+kind of entry becomes rows, ``rendering`` how a tool call is phrased, ``rows`` how a
+row is measured and timed, ``projection`` the agent events that fill the list as a
+request runs, and ``replay`` the stored branch that rebuilds it on a resume.
+"""

zettcode/app/agent/conversation/changes.py

@@ -0,0 +1,64 @@
+"""What a request did to the files, added up: the data behind the summary at the end of a turn."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import PurePath
+
+from zettcode.plugin_api.entries import DeleteEntry, Entry, EntryStatus, FileChangeEntry, FileSummary
+
+
+def shown_path(path: str, workspace: PurePath | None) -> str:
+    """Return a file as the reader knows it: relative to the workspace when it is inside it.
+
+    The model names the same file as ``app.py`` in one call and as ``/work/app.py`` in the next, and
+    the summary must not count them twice. Only the text is looked at, never the disk.
+
+    Args:
+        path: The path as the call named it.
+        workspace: The directory the session works in, or ``None`` to leave every path as it is.
+    """
+    if workspace is None or not path:
+        return path
+    candidate = PurePath(path)
+    # Rooted, not only absolute: on Windows ``/work/a.py`` has a root and no drive, which is not
+    # "absolute" to pathlib, and it still has to be compared with the workspace it is inside.
+    if candidate.is_absolute() or candidate.root:
+        try:
+            return candidate.relative_to(workspace).as_posix()
+        except ValueError:
+            return path
+    return candidate.as_posix()
+
+
+def changed_files(entries: Iterable[Entry], workspace: PurePath | None = None) -> tuple[FileSummary, ...]:
+    """Return the files a run of entries changed, each once, in the order they were first touched.
+
+    Only a call that *succeeded* counts: a failed edit changed nothing, and a skipped one never ran.
+    A file changed several times is one row with the totals. A file deleted and then written again is
+    a file that exists, counted from the write, and one written and then deleted is deleted.
+
+    Args:
+        entries: The entries of one request, in order; anything that is not a file change is ignored.
+        workspace: The directory paths are shown relative to.
+    """
+    order: list[str] = []
+    totals: dict[str, FileSummary] = {}
+    for entry in entries:
+        if not isinstance(entry, (FileChangeEntry, DeleteEntry)) or entry.status is not EntryStatus.COMPLETED:
+            continue
+        if not entry.path:
+            continue
+        path = shown_path(entry.path, workspace)
+        if path not in totals:
+            order.append(path)
+            totals[path] = FileSummary(path)
+        current = totals[path]
+        if isinstance(entry, DeleteEntry):
+            totals[path] = FileSummary(path, deleted=True)
+            continue
+        base = FileSummary(path) if current.deleted else current
+        totals[path] = FileSummary(
+            path, base.added + entry.added, base.removed + getattr(entry, "removed", 0), deleted=False
+        )
+    return tuple(totals[path] for path in order)