zettcode-engine 0.3.4__py3-none-any.whl

zettcode/config_edit.py

@@ -0,0 +1,457 @@
+"""Edit the ``[[models]]`` entries of the config file without disturbing the rest of it.
+
+The file is the reader's: it has comments they wrote, tables this code has never heard of, and a
+layout they chose. Rewriting it from parsed data would throw all of that away, so the edits here are
+made on the *text* — one ``[[models]]`` block is added, replaced or removed — and everything outside
+that block is left byte for byte as it was.
+
+Because text editing is only safe when the text is what it looks like, every edit is checked before
+it is written: the result must parse, must hold exactly the models the edit meant it to, and every
+table other than ``models`` must be equal to what it was. A file that spells its models some other
+way (an inline array, say) is refused rather than guessed at, and a refused or failed edit writes
+nothing.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import tempfile
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from zettcode._compat import tomllib
+from zettcode.config import MODEL_KEYS, ModelConfig, _read_models
+
+#: A line that opens a table or an array of tables; the first thing on it, so a ``[`` inside a value
+#: or a comment is not one.
+_HEADER = re.compile(r"^\s*\[")
+#: The line that opens one model.
+_MODEL_HEADER = re.compile(r"^\s*\[\[\s*models\s*\]\]\s*(#.*)?$")
+
+#: The order keys are written in, so a new entry reads the way the documentation shows one.
+_KEY_ORDER = (
+    "display_model",
+    "model",
+    "base_url",
+    "token",
+    "chat",
+    "anthropic",
+    "responses_api",
+    "multimodal",
+    "temperature",
+    "web_search",
+    "web_search_name",
+    "context_window",
+    "compact_percent",
+    "reasoning_efforts",
+)
+
+
+class ConfigEditError(ValueError):
+    """The file could not be edited safely; its message says why and nothing was written."""
+
+
+def toml_string(value: str) -> str:
+    """Return ``value`` as a TOML basic string, escaping what a basic string cannot hold."""
+    out = ['"']
+    for character in value:
+        code = ord(character)
+        if character == '"':
+            out.append('\\"')
+        elif character == "\\":
+            out.append("\\\\")
+        elif character == "\n":
+            out.append("\\n")
+        elif character == "\t":
+            out.append("\\t")
+        elif code < 0x20 or code == 0x7F:
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(character)
+    out.append('"')
+    return "".join(out)
+
+
+def _value(value: object) -> str:
+    """Render one setting's value."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return toml_string(value)
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, (list, tuple)) and all(isinstance(item, str) for item in value):
+        return "[" + ", ".join(toml_string(item) for item in value) + "]"
+    raise ConfigEditError(f"cannot write a value of type {type(value).__name__}")
+
+
+def render_entry(entry: Mapping[str, object]) -> str:
+    """Return one ``[[models]]`` block for ``entry``, keys in the documented order.
+
+    Args:
+        entry: The keys of one model as they are written in the file.
+    """
+    unknown = sorted(set(entry) - MODEL_KEYS)
+    if unknown:
+        raise ConfigEditError(f"unknown model keys: {', '.join(unknown)}")
+    lines = ["[[models]]"]
+    for key in _KEY_ORDER:
+        if key in entry:
+            lines.append(f"{key} = {_value(entry[key])}")
+    return "\n".join(lines) + "\n"
+
+
+def entry_from_model(model: ModelConfig, *, token: str | None = None) -> dict[str, object]:
+    """Return the file keys for ``model``, leaving out whatever is the default.
+
+    Args:
+        model: A validated model.
+        token: What to write for the token; ``None`` writes the one the model holds.
+    """
+    from zettcode.config import DEFAULT_COMPACT_PERCENT, DEFAULT_CONTEXT_WINDOW
+
+    written = model.token if token is None else token
+    entry: dict[str, object] = {"model": model.model}
+    if written:
+        entry["token"] = written
+    if model.display_model:
+        entry["display_model"] = model.display_model
+    if model.base_url:
+        entry["base_url"] = model.base_url
+    if model.anthropic:
+        entry["anthropic"] = True
+    if model.responses_api:
+        entry["responses_api"] = True
+    if model.chat:
+        entry["chat"] = True
+    if model.multimodal:
+        entry["multimodal"] = True
+    if model.temperature is not None:
+        entry["temperature"] = model.temperature
+    if model.web_search:
+        entry["web_search"] = True
+    if model.web_search_name:
+        entry["web_search_name"] = model.web_search_name
+    if model.context_window != DEFAULT_CONTEXT_WINDOW:
+        entry["context_window"] = model.context_window
+    if model.compact_percent != DEFAULT_COMPACT_PERCENT:
+        entry["compact_percent"] = model.compact_percent
+    if model.reasoning_efforts:
+        entry["reasoning_efforts"] = [level.value for level in model.reasoning_efforts]
+    return entry
+
+
+def _blocks(lines: list[str]) -> list[tuple[int, int]]:
+    """Return the ``(start, end)`` line range of every ``[[models]]`` block, in order.
+
+    A block runs to the next table header, less the blank and comment lines at its end: those are
+    the introduction to whatever follows, and belong to it.
+    """
+    blocks: list[tuple[int, int]] = []
+    for index, line in enumerate(lines):
+        if not _MODEL_HEADER.match(line):
+            continue
+        end = len(lines)
+        for later in range(index + 1, len(lines)):
+            if _HEADER.match(lines[later]):
+                end = later
+                break
+        while end > index + 1 and (not lines[end - 1].strip() or lines[end - 1].lstrip().startswith("#")):
+            end -= 1
+        blocks.append((index, end))
+    return blocks
+
+
+def _parse(text: str, where: Path) -> dict[str, Any]:
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigEditError(f"{where} is not valid TOML: {error}") from error
+
+
+def _guarded(text: str, where: Path) -> tuple[list[str], list[tuple[int, int]], dict[str, Any]]:
+    """Return the file's lines, its model blocks and its data, or refuse a layout this cannot edit.
+
+    A file with no ``[[models]]`` table at all is an empty list of models rather than a layout to refuse: that is
+    what a fresh machine has, and ``/config`` is how the first entry is written into it.
+    """
+    data = _parse(text, where)
+    declared = data.get("models") is not None
+    models = data.get("models")
+    if models is None:
+        models = []
+        data = {**data, "models": models}
+    if not isinstance(models, list) or not all(isinstance(entry, dict) for entry in models):
+        raise ConfigEditError(f"{where} has no [[models]] entries to edit")
+    lines = text.split("\n")
+    blocks = _blocks(lines)
+    if len(blocks) != len(models):
+        raise ConfigEditError(
+            f"{where} writes its models in a way /config cannot edit safely "
+            f"({len(models)} models, {len(blocks)} [[models]] blocks); edit the file by hand"
+        )
+    if declared and not blocks:
+        # `models = []`, or the key spelled some other way: this writes `[[models]]` blocks, and a second spelling
+        # of the same key cannot be added beside it — `models = []` plus one block is not TOML at all.
+        raise ConfigEditError(f"{where} writes 'models' as a value, which /config cannot edit; edit the file by hand")
+    return lines, blocks, data
+
+
+def _checked(new_text: str, before: dict[str, Any], expected: list[dict[str, Any]], where: Path) -> None:
+    """Refuse a result that does not hold what the edit meant it to, before anything is written."""
+    after = _parse(new_text, where)
+    if after.get("models") != expected:
+        raise ConfigEditError("the edit did not produce the models it meant to; nothing was written")
+    others_before = {key: value for key, value in before.items() if key != "models"}
+    others_after = {key: value for key, value in after.items() if key != "models"}
+    if others_before != others_after:
+        raise ConfigEditError("the edit would have changed something other than the models; nothing was written")
+    models = after.get("models")
+    try:
+        _read_models(models, where)
+    except ValueError as error:
+        raise ConfigEditError(str(error)) from error
+
+
+def add_model(text: str, entry: Mapping[str, object], *, where: Path) -> str:
+    """Return ``text`` with one more model after the last, which is where a reader looks for it.
+
+    Args:
+        text: The config file as it is.
+        entry: The new model's keys.
+        where: The file's path, for messages.
+    """
+    lines, blocks, data = _guarded(text, where)
+    block = render_entry(entry).rstrip("\n").split("\n")
+    expected = [*data["models"], dict(_parse(render_entry(entry), where)["models"][0])]
+    if blocks:
+        at = blocks[-1][1]
+        result = "\n".join([*lines[:at], "", *block, *lines[at:]])
+    else:
+        # Nothing to insert after: the entry goes at the end, set apart from whatever the file holds by one blank
+        # line, and a file that holds nothing gets no leading blank line.
+        head = text.rstrip()
+        body = "\n".join(block)
+        result = f"{head}\n\n{body}\n" if head else f"{body}\n"
+    _checked(result, data, expected, where)
+    return result
+
+
+def replace_model(text: str, index: int, entry: Mapping[str, object], *, where: Path) -> str:
+    """Return ``text`` with model number ``index`` (from zero) rewritten as ``entry``.
+
+    Comments inside that one block are not kept; those above it and everywhere else are.
+    """
+    lines, blocks, data = _guarded(text, where)
+    if not 0 <= index < len(blocks):
+        raise ConfigEditError(f"there is no model number {index + 1}")
+    start, end = blocks[index]
+    new = [*lines[:start], *render_entry(entry).rstrip("\n").split("\n"), *lines[end:]]
+    expected = list(data["models"])
+    expected[index] = dict(_parse(render_entry(entry), where)["models"][0])
+    result = "\n".join(new)
+    _checked(result, data, expected, where)
+    return result
+
+
+def remove_model(text: str, index: int, *, where: Path) -> str:
+    """Return ``text`` without model number ``index`` (from zero). The last one cannot be removed."""
+    lines, blocks, data = _guarded(text, where)
+    if not 0 <= index < len(blocks):
+        raise ConfigEditError(f"there is no model number {index + 1}")
+    if len(blocks) == 1:
+        raise ConfigEditError("that is the only model; add another before removing it")
+    start, end = blocks[index]
+    # The blank line that set the block apart goes with it, so removing leaves no gap behind.
+    if start > 0 and not lines[start - 1].strip():
+        start -= 1
+    new = [*lines[:start], *lines[end:]]
+    expected = list(data["models"])
+    del expected[index]
+    result = "\n".join(new)
+    _checked(result, data, expected, where)
+    return result
+
+
+def _opened_by_subtables(lines: Sequence[str], table: str, key: str, value: object) -> bool:
+    """Return whether the file opens ``table`` only through sub-tables of it, with none of them called ``key``.
+
+    A file that writes ``[plugins.recap]`` has a ``plugins`` table the moment it parses, although no line ever says
+    ``[plugins]``; TOML lets a parent be declared after its children, so the key can still be written under a header
+    appended at the end. That holds only when the file does not assign the table itself, inline (``plugins = {...}``)
+    or through dotted keys (``plugins.disable = []``): a table assigned like that cannot be declared a second time.
+    A sub-table already called ``key`` (``[plugins.disable]``) cannot be written at all: the key and the table would
+    be one name declared twice. One case is refused although TOML would take it, because nobody has needed it and the
+    check after the edit is what keeps a wider rule honest: an entry of the table that is not a plain sub-table (an
+    array of tables, ``[[plugins.notes]]``). Anything refused is left for the reader to edit by hand.
+
+    This looks at lines, not at TOML, so it knows the spellings it was written for: a bare or quoted first segment.
+    A spelling it cannot see makes the appended header invalid, which the edit's own check catches and reports as a
+    file it cannot edit, so a miss costs a refusal and never a wrong file.
+    """
+    first = rf"(?:{re.escape(table)}|\"{re.escape(table)}\"|'{re.escape(table)}')"
+    assigned = re.compile(rf"^\s*{first}\s*[.=]")
+    if any(assigned.match(item) for item in lines):
+        return False
+    if not isinstance(value, dict) or not value or key in value:
+        return False
+    return all(isinstance(item, dict) for item in value.values())
+
+
+def _set_key(text: str, table: str, key: str, literal: str, value: object, *, where: Path, command: str) -> str:
+    """Return ``text`` with ``[table] key`` set to ``value``, touching nothing else.
+
+    The key's line is replaced where the file already has one, added under an existing header, or the
+    table is appended at the end. The result is checked before it is returned: it must parse and differ
+    from the original in nothing but this key. A file that spells the table some other way (an inline
+    table, say) is refused rather than guessed at; a table it opens only through a sub-table of it, as
+    ``[plugins.recap]`` opens ``plugins``, gets a header of its own appended (see
+    :func:`_opened_by_subtables`).
+
+    Args:
+        table: The table's name (``"ui"``).
+        key: The key in it (``"theme"``).
+        literal: ``value`` as TOML spells it (``'"nord"'``, ``"true"``).
+        value: What the key must read back as.
+        where: The file, for messages.
+        command: What the reader ran, for the message when the file cannot be edited safely.
+    """
+    header_pattern = re.compile(rf"^\s*\[\s*{re.escape(table)}\s*\]\s*(#.*)?$")
+    key_pattern = re.compile(rf"^\s*{re.escape(key)}\s*=")
+    before = _parse(text, where)
+    lines = text.split("\n")
+    line = f"{key} = {literal}"
+    header = next((index for index, item in enumerate(lines) if header_pattern.match(item)), None)
+    if header is None:
+        if table in before and not _opened_by_subtables(lines, table, key, before[table]):
+            raise ConfigEditError(
+                f"{where} writes [{table}] in a way {command} cannot edit safely; edit the file by hand"
+            )
+        while lines and not lines[-1].strip():
+            lines.pop()
+        new = [*lines, "", f"[{table}]", line, ""]
+    else:
+        end = next((i for i in range(header + 1, len(lines)) if _HEADER.match(lines[i])), len(lines))
+        existing = next((i for i in range(header + 1, end) if key_pattern.match(lines[i])), None)
+        if existing is not None:
+            new = [*lines[:existing], line, *lines[existing + 1 :]]
+        else:
+            new = [*lines[: header + 1], line, *lines[header + 1 :]]
+    result = "\n".join(new)
+    try:
+        after = _parse(result, where)
+    except ConfigEditError as error:
+        # ``text`` parsed above, so it is this edit that made the file unreadable, not the reader: a table spelled in a
+        # way the line patterns above do not see (a quoted ``"plugins"``, say) is one the edit cannot make room in.
+        raise ConfigEditError(
+            f"{where} writes [{table}] in a way {command} cannot edit safely; edit the file by hand"
+        ) from error
+    table_before = {name: item for name, item in before.get(table, {}).items() if name != key}
+    table_after = {name: item for name, item in after.get(table, {}).items() if name != key}
+    others_before = {name: item for name, item in before.items() if name != table}
+    others_after = {name: item for name, item in after.items() if name != table}
+    if after.get(table, {}).get(key) != value or table_before != table_after or others_before != others_after:
+        raise ConfigEditError(f"the edit would have changed something other than {table}.{key}; nothing was written")
+    return result
+
+
+def set_theme(text: str, name: str, *, where: Path) -> str:
+    """Return ``text`` with ``[ui] theme`` set to ``name``, touching nothing else.
+
+    Like the model edits it is checked before it is returned: the result must parse and differ from the
+    original in nothing but ``ui.theme``.
+    """
+    return _set_key(text, "ui", "theme", toml_string(name), name, where=where, command="/theme")
+
+
+def set_pet(text: str, name: str, *, where: Path) -> str:
+    """Return ``text`` with ``[ui] pet`` set to ``name``, touching nothing else."""
+    return _set_key(text, "ui", "pet", toml_string(name), name, where=where, command="/pet")
+
+
+def set_pet_position(text: str, across: float, down: float, *, where: Path) -> str:
+    """Return ``text`` with ``[ui] pet_position`` set to where the pet was left, touching nothing else.
+
+    The shares are rounded to three places: a pet moves a cell at a time, and a number such as
+    ``0.8571428571428571`` in a file the reader reads and edits is noise.
+    """
+    shares = [round(min(1.0, max(0.0, across)), 3), round(min(1.0, max(0.0, down)), 3)]
+    literal = "[" + ", ".join(repr(share) for share in shares) + "]"
+    return _set_key(text, "ui", "pet_position", literal, shares, where=where, command="the pet")
+
+
+def set_self_compaction(text: str, enabled: bool, *, where: Path) -> str:
+    """Return ``text`` with ``[compaction] self`` set to ``enabled``, touching nothing else."""
+    return _set_key(
+        text, "compaction", "self", "true" if enabled else "false", enabled, where=where, command="/plugins"
+    )
+
+
+def set_string_list(text: str, table: str, key: str, values: Sequence[str], *, where: Path, command: str) -> str:
+    """Return ``text`` with ``[table] key`` set to an array of strings, touching nothing else.
+
+    The array is written on one line, in the order given; the result is checked the way every other key edit is.
+    """
+    literal = "[" + ", ".join(toml_string(value) for value in values) + "]"
+    return _set_key(text, table, key, literal, list(values), where=where, command=command)
+
+
+def set_boolean(text: str, table: str, key: str, enabled: bool, *, where: Path, command: str) -> str:
+    """Return ``text`` with ``[table] key`` set to a boolean, touching nothing else.
+
+    One key of one table, written and checked the way every other single-key edit is: a file that cannot take it is
+    refused whole rather than half-written.
+
+    Args:
+        text: The configuration as it is now.
+        table: The table's name (``"skills"``).
+        key: The key in it (``"enabled"``).
+        enabled: What it should read back as.
+        where: The file, for messages.
+        command: What the reader pressed, for the message when the file cannot be edited safely.
+    """
+    return _set_key(text, table, key, "true" if enabled else "false", enabled, where=where, command=command)
+
+
+def set_statusline(text: str, shown: Mapping[str, bool], *, where: Path) -> str:
+    """Return ``text`` with each named part of ``[statusline]`` set to shown or hidden, touching nothing else.
+
+    A part is a key of the table (``ctx = false`` hides it, ``ctx = true`` shows it again). Each key is
+    written and checked on its own, as the other single-key edits are, so a file that cannot take one is
+    refused whole rather than half-written.
+    """
+    for name, visible in shown.items():
+        text = _set_key(
+            text, "statusline", name, "true" if visible else "false", visible, where=where, command="/statusline"
+        )
+    return text
+
+
+def file_entries(text: str, *, where: Path) -> list[dict[str, Any]]:
+    """Return the models as the file writes them (a token left to the environment stays absent); none is a list."""
+    return list(_guarded(text, where)[2].get("models") or [])
+
+
+def write_text_atomically(path: Path, text: str) -> None:
+    """Replace ``path`` with ``text`` so a crash leaves the old file or the new one, never half.
+
+    The new file takes the old one's permissions: the file holds tokens, and a reader who made it
+    private has not asked for that to change by adding a model.
+    """
+    path = path.expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = path.stat().st_mode & 0o777 if path.exists() else 0o600
+    handle, name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8", newline="") as file:
+            file.write(text)
+        with contextlib.suppress(OSError):  # not every file system keeps modes
+            os.chmod(name, mode)
+        os.replace(name, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(name)
+        raise

zettcode/engine/__init__.py

@@ -0,0 +1,39 @@
+"""The engine: the one agent core that the terminal and the SDK both drive.
+
+Most programs want :mod:`zettcode.sdk`, which is the documented, stable surface. The engine is here for the ones that
+need the core itself, and it stays small on purpose; see ``docs/internal/engine.md`` and
+``docs/internal/namespace-split.md``. It imports nothing else of ours: the plugin set it runs, the line to the other
+sessions and the MCP client are the SDK's, passed in by whoever builds the runtime. Names load on first use, so
+importing one submodule does not build the rest.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "ZettCodeEngine": ".core",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from .core import ZettCodeEngine
+
+
+def __getattr__(name: str) -> object:
+    """Import the module a public name lives in, the first time it is asked for."""
+    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__ = ["ZettCodeEngine"]

zettcode/engine/agent/__init__.py

@@ -0,0 +1,81 @@
+"""The agent: one class, assembled from the parts that make it up.
+
+The class used to be one 750-line body doing eight unrelated jobs. It is divided by what each part is responsible for:
+
+==============  ===========================================================================
+``base``        :class:`AgentBase` — the engine, the workspace, the active session id
+``settings``    :class:`SettingsMixin` — model, reasoning effort, shell permission
+``context``     :class:`ContextMixin` — the request the next turn carries; compaction
+``sessions``    :class:`SessionsMixin` — switch, resume, fork, list, and title sessions
+``turns``       :class:`TurnsMixin` — build a request, stream its events, steer it
+``interaction`` :class:`InteractionMixin` — answer an approval request or a question
+``exports``     :class:`ExportsMixin` — write a session out as a page
+``prompt``      the parts of a user turn: text, ``@`` references, images (no class)
+==============  ===========================================================================
+
+A mixin inherits the ones whose methods it really calls, and :class:`AgentBase` below all of them, so each is
+type-checked against what it relies on; nothing is declared twice. This class is the composition and the
+lifecycle — building the engine, and closing it. It knows nothing of the terminal: the terminal's commands and
+preferences are a subclass of its own (``zettcode.app.agent.agent.TerminalAgent``).
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from zettcode.config import ZettCodeConfig
+from zettcode.engine.core import PluginLoader, ZettCodeEngine
+
+from .context import ContextMixin
+from .exports import ExportsMixin
+from .interaction import InteractionMixin
+from .sessions import SessionsMixin
+from .settings import SettingsMixin
+from .turns import TurnsMixin
+
+__all__ = ["ZettCodeAgent"]
+
+AgentT = TypeVar("AgentT", bound="ZettCodeAgent")
+
+
+class ZettCodeAgent(
+    InteractionMixin,
+    TurnsMixin,
+    ExportsMixin,
+    SessionsMixin,
+    SettingsMixin,
+    ContextMixin,
+):
+    """Expose agent operations without leaking engine resources to the front end.
+
+    The engine assembles the vendor client and extensions; this class is the entry point for turns, session and
+    model selection, progress, and responses to approval requests.
+    """
+
+    def __init__(self, runtime: ZettCodeEngine) -> None:
+        self.runtime = runtime
+
+    @classmethod
+    async def create(cls: type[AgentT], config: ZettCodeConfig, load: PluginLoader) -> AgentT:
+        """Build the engine with the plugin set the caller chose, and wrap it in the agent.
+
+        The loader is required: the engine ships no built-in plugin, so a runtime built without one has no tools, no
+        session store and no approval — and the front ends that know which agent they want are the SDK
+        (:func:`zettcode.sdk.builtins.load_agent_plugins`) and the terminal
+        (:func:`zettcode.app.plugins.loader.terminal_plugins`).
+        """
+        return cls(await ZettCodeEngine.create(config, load))
+
+    @classmethod
+    def preview(cls: type[AgentT], config: ZettCodeConfig, load: PluginLoader) -> AgentT:
+        """Wrap an engine that still has to start, so a front end can paint first.
+
+        The engine here holds the session and the extensions the loader's plugins contribute; the provider SDK and
+        the client are built by the first :meth:`runtime.start`, which a turn or a command awaits. Everything a front
+        end reads per frame — the model, the effort, the session, the usage — is answered from that preview.
+        """
+        return cls(ZettCodeEngine.preview(config, load))
+
+    async def aclose(self) -> None:
+        """Release the underlying engine resources."""
+        await self.runtime.aclose()

zettcode/engine/agent/base.py

@@ -0,0 +1,60 @@
+"""What every part of the agent shares: the runtime it speaks to, and who and where it is.
+
+The mixins in this package are split by what they are responsible for, and each one
+inherits this class only to be type-checked against what the others rely on. The two
+properties here are read by nearly all of them, which is why they live below all of them.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from zettcode.engine.core import ZettCodeEngine
+from zettcode.engine.storage import SessionLocked
+from zettcode.mention import MentionProvider
+
+
+class AgentBase:
+    """The runtime, the workspace it works in, and the session the next turn belongs to."""
+
+    #: The runtime this agent speaks to; the one thing the application agent holds.
+    runtime: ZettCodeEngine
+
+    @property
+    def workspace(self) -> Path:
+        """Return the workspace displayed in the header."""
+        return self.runtime.config.workspace
+
+    @property
+    def session_id(self) -> str:
+        """Return the session used for the next turn."""
+        return self.runtime.session_id
+
+    @property
+    def plugin_mentions(self) -> tuple[MentionProvider, ...]:
+        """Return the ``@`` resource providers the installed plugins registered."""
+        return self.runtime.plugins.mentions
+
+    @property
+    def session_locked(self) -> bool:
+        """Return whether another process has the active session open, so that this one may only read it.
+
+        Every session is locked by the process that has it open (see :mod:`..storage.locks`). A session this
+        process started is always its own; one it resumed may be somebody else's, and then it is shown and
+        nothing is written to it: no turn, no title, no compaction.
+        """
+        return self.runtime.session_locked
+
+    def retake_session(self) -> bool:
+        """Try again to lock the active session; return whether this process holds it now."""
+        return self.runtime.retake_session()
+
+    def require_session(self) -> None:
+        """Refuse to go on when the active session is another process's.
+
+        Raises:
+            SessionLocked: The lock is not held. A ``ValueError``, which the shell shows as a line in the
+                conversation.
+        """
+        if self.session_locked:
+            raise SessionLocked()