zettcode-engine 0.3.4__py3-none-any.whl

zettcode/logging_setup.py

@@ -0,0 +1,196 @@
+"""Process-wide setup for the standard-library loggers.
+
+Every component uses ordinary ``logging`` calls::
+
+    logger = logging.getLogger("zettcode.terminal")
+    logger.info("turn.start", extra={"session": session})
+    logger.exception("turn.failed")
+
+``setup`` adds one rotating JSON-lines handler under ``~/.zettcode/log``. The
+terminal's stderr capture stays in ``tui.log``; structured events go to
+``terminal.jsonl`` so rotation never renames the file fd 2 writes to.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from typing import Any
+
+DEFAULT_MAX_BYTES = 8 * 1024 * 1024
+DEFAULT_BACKUPS = 3
+MAX_MESSAGE = 2_000
+MAX_TRACEBACK = 20_000
+MAX_RECORD_CHARS = 64_000
+DEFAULT_DIR = Path.home() / ".zettcode" / "log"
+
+_LEVELS = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING, "error": logging.ERROR}
+_RESERVED = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "message",
+        "asctime",
+    }
+)
+
+
+def _env_positive(name: str, default: int) -> int:
+    try:
+        value = int(os.getenv(name, ""))
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+def _env_non_negative(name: str, default: int) -> int:
+    try:
+        value = int(os.getenv(name, ""))
+    except ValueError:
+        return default
+    return value if value >= 0 else default
+
+
+def level() -> int:
+    """Return the configured threshold; an unknown value falls back to info."""
+    return _LEVELS.get(os.getenv("ZETTCODE_LOG_LEVEL", "info").strip().lower(), logging.INFO)
+
+
+def log_path(component: str) -> Path:
+    """Return the JSONL file for one component."""
+    return DEFAULT_DIR / f"{component}.jsonl"
+
+
+class _OwnerRotatingHandler(RotatingFileHandler):
+    """Rotating handler that creates its file owner-only, not with the umask."""
+
+    def _open(self) -> Any:
+        stream = super()._open()
+        if os.name != "nt":
+            try:
+                os.chmod(self.baseFilename, 0o600)
+            except OSError:
+                pass
+        return stream
+
+
+class JsonFormatter(logging.Formatter):
+    """One JSON object per record, including the caller's ``extra`` fields."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "time": datetime.fromtimestamp(record.created, timezone.utc).isoformat(timespec="milliseconds"),
+            "level": record.levelname.lower(),
+            "logger": record.name,
+            "event": record.getMessage()[:MAX_MESSAGE],
+            "pid": record.process,
+        }
+        for key, value in record.__dict__.items():
+            if key not in _RESERVED and not key.startswith("_"):
+                payload[key] = value
+        if record.exc_info is not None:
+            formatted = self.formatException(record.exc_info)
+            if len(formatted) > MAX_TRACEBACK:
+                marker = "\n<traceback truncated>\n"
+                keep = MAX_TRACEBACK - len(marker)
+                head, tail = keep // 2, keep - keep // 2
+                formatted = formatted[:head] + marker + formatted[-tail:]
+            payload["traceback"] = formatted
+        line = json.dumps(payload, ensure_ascii=False, default=str)
+        if len(line) > MAX_RECORD_CHARS:
+            line = json.dumps(
+                {
+                    "time": payload["time"],
+                    "level": payload["level"],
+                    "logger": payload["logger"],
+                    "event": payload["event"],
+                    "pid": payload["pid"],
+                    "truncated": True,
+                    "original_chars": len(line),
+                },
+                ensure_ascii=False,
+            )
+        return line
+
+
+def ensure_log_parent(path: Path) -> None:
+    """Create the folder a log file lives in, owner-only when this call made it."""
+    parent = path.parent
+    created = not parent.exists()
+    parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    if created and os.name != "nt":
+        try:
+            os.chmod(parent, 0o700)
+        except OSError:
+            pass
+
+
+def setup(component: str, *, path: Path | None = None) -> logging.Logger:
+    """Configure and return ``zettcode.<component>``; safe to call repeatedly."""
+    logger = logging.getLogger(f"zettcode.{component}")
+    logging.raiseExceptions = False
+    logger.setLevel(level())
+    logger.propagate = False
+    logger.handlers.clear()
+    target = path or log_path(component)
+    try:
+        ensure_log_parent(target)
+        handler: logging.Handler = _OwnerRotatingHandler(
+            target,
+            maxBytes=_env_positive("ZETTCODE_LOG_MAX_BYTES", DEFAULT_MAX_BYTES),
+            backupCount=_env_non_negative("ZETTCODE_LOG_BACKUPS", DEFAULT_BACKUPS),
+            encoding="utf-8",
+            delay=True,
+        )
+    except OSError:
+        handler = logging.NullHandler()
+    handler.setLevel(logging.DEBUG)
+    handler.setFormatter(JsonFormatter())
+    logger.addHandler(handler)
+    if not isinstance(handler, logging.NullHandler) and os.name != "nt":
+        try:
+            os.chmod(target, 0o600)
+        except OSError:
+            pass
+    return logger
+
+
+def rotate_text(path: Path, *, max_bytes: int | None = None, backups: int | None = None) -> None:
+    """Rotate a text log at startup, before a raw stderr fd opens it."""
+    limit = max_bytes if max_bytes is not None else _env_positive("ZETTCODE_LOG_MAX_BYTES", DEFAULT_MAX_BYTES)
+    count = backups if backups is not None else _env_non_negative("ZETTCODE_LOG_BACKUPS", DEFAULT_BACKUPS)
+    try:
+        if not path.is_file() or path.stat().st_size <= limit:
+            return
+        if count <= 0:
+            path.unlink(missing_ok=True)
+            return
+        for index in range(count - 1, 0, -1):
+            source = path.with_name(f"{path.name}.{index}")
+            if source.exists():
+                source.replace(path.with_name(f"{path.name}.{index + 1}"))
+        path.replace(path.with_name(f"{path.name}.1"))
+    except OSError:
+        pass

zettcode/mention.py

@@ -0,0 +1,124 @@
+"""What an ``@`` reference is, and the shape a provider of them has.
+
+The runtime resolves references against providers a plugin hands it (:class:`zettcode.engine.plugins.PluginContext`),
+so the type is the engine's: a plugin that offers resources implements this, and the engine reads it without knowing
+whether the resources are files, skills or other sessions. The implementations and the registry over them are
+:mod:`zettcode.mentions`, which ships with the SDK.
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from zettcode.registry import Provider, Registry
+
+#: One mention token: an ``@`` at a word boundary, then a name. A name is what a
+#: skill is called (lowercase words) or where a file lives (``src/app.py``), so it
+#: holds path punctuation as well; it starts with a letter, a digit, or an
+#: underscore, which is what keeps ``@/`` and a trailing ``@`` out. The lookbehind
+#: keeps an email address or a second ``@`` from matching.
+MENTION = re.compile(r"(?<![\w@])@([A-Za-z0-9_][A-Za-z0-9_./-]*)")
+
+
+@dataclass(frozen=True, slots=True)
+class Mention:
+    """One resource a draft can reference.
+
+    Attributes:
+        token: Text as typed, e.g. ``@code-review``.
+        kind: Provider that owns the resource, e.g. ``"skill"``.
+        name: Resource name without the ``@``.
+        description: One line shown by the completion menu.
+    """
+
+    token: str
+    kind: str
+    name: str
+    description: str
+
+
+class MentionProvider(Provider[Mention], ABC):
+    """One kind of ``@`` resource: what it offers and what it injects."""
+
+    #: Short name shown in the completion menu's type column, e.g. ``"skill"``.
+    kind: str
+
+    @abstractmethod
+    def candidates(self, query: str) -> Sequence[Mention]:
+        """Return the resources whose name matches ``query`` (without the ``@``)."""
+
+    @property
+    def items(self) -> Sequence[Mention]:
+        """Return every resource this provider offers."""
+        return self.candidates("")
+
+    @abstractmethod
+    def expand(self, name: str) -> str | None:
+        """Return the text one resource injects, or ``None`` when it is unknown."""
+
+    def rename(self, name: str) -> str | None:
+        """Return the words the model reads in place of ``@name``, or ``None`` to leave the token as typed.
+
+        Most references are meaningful to the model as they are (a path, a skill's name). One that is not —
+        the name of another session — is replaced, so the model is not left holding a word it must guess at.
+        """
+        return None
+
+
+class MentionRegistry(Registry[Mention]):
+    """The providers a draft is resolved against, in registration order."""
+
+    def __init__(self, providers: Sequence[MentionProvider] = ()) -> None:
+        """Keep the providers; the first to claim a name wins a duplicate."""
+        super().__init__(providers)
+
+    def candidates(self, query: str) -> tuple[Mention, ...]:
+        """Return every resource whose name matches ``query`` (which has no ``@``).
+
+        Each provider is asked for the query rather than handed every item it has:
+        a draft is completed on every keystroke, and the file provider holds
+        thousands of names it would otherwise build a ``Mention`` for each time.
+        An earlier provider still wins a duplicate name.
+        """
+        seen: set[str] = set()
+        merged: list[Mention] = []
+        for provider in self.mention_providers:
+            for mention in provider.candidates(query):
+                if mention.name in seen:
+                    continue
+                seen.add(mention.name)
+                merged.append(mention)
+        return tuple(merged)
+
+    @property
+    def mention_providers(self) -> tuple[MentionProvider, ...]:
+        """Return the providers as the ``@``-specific type that can expand tokens."""
+        return tuple(provider for provider in self.providers if isinstance(provider, MentionProvider))
+
+    def expand_token(self, token: str) -> str | None:
+        """Resolve one typed ``@`` token into the text it contributes, if any.
+
+        The shell gets the tokens from the composer's parts rather than scanning
+        the draft, so this is handed ``"@name"`` exactly as it was written.
+        """
+        name = token[1:] if token.startswith("@") else token
+        for provider in self.mention_providers:
+            block = provider.expand(name)
+            if block is not None:
+                return block
+        return None
+
+    def rename_token(self, token: str) -> str | None:
+        """Return the words the model reads in place of one typed token, from the provider that owns it.
+
+        The owner is the first provider that knows the name, which is the one :meth:`expand_token` asks:
+        a session and a file with one name are the session.
+        """
+        name = token[1:] if token.startswith("@") else token
+        for provider in self.mention_providers:
+            if provider.expand(name) is not None:
+                return provider.rename(name)
+        return None

zettcode/modes.py

@@ -0,0 +1,18 @@
+"""How a message asks to be handled by a recipient that is busy with a request.
+
+A leaf with no imports, so the broker, the SDK, the server and the shell can name the two modes without one of them
+depending on another. The broker's protocol re-exports these names, because that is where they are checked; an
+unknown value is refused there, and a missing one means :data:`MODE_STEER`.
+"""
+
+from __future__ import annotations
+
+#: Hand the message to the request that is running, so it changes course.
+MODE_STEER = "steer"
+
+#: Wait until the request that is running ends.
+MODE_FOLLOWUP = "followup"
+
+MODES = (MODE_STEER, MODE_FOLLOWUP)
+
+__all__ = ["MODE_FOLLOWUP", "MODE_STEER", "MODES"]

zettcode/paths.py

@@ -0,0 +1,113 @@
+"""Where ZettCode keeps its own files.
+
+Constants only, and deliberately importable without the settings module: the
+shell takes the terminal and points its diagnostics at the log before it has
+read the config, so the paths cannot live behind that import.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+
+#: The conventional config file, read when the user has created one.
+CONFIG_FILE = Path.home() / ".zettcode" / "config.toml"
+
+#: Session storage is an application default, not a model setting.
+DEFAULT_STORE = Path.home() / ".zettcode" / "sessions"
+
+#: Plugins the reader switched off with ``/plugins disable``; read at the next start. Kept beside the store so the
+#: reader's config file stays theirs, and a name here is an entry-point name, the same one ``[plugins] disable`` takes.
+DEFAULT_PLUGINS_FILE = DEFAULT_STORE.parent / "plugins.json"
+
+#: A plugin that is a single ``.py`` file lives here instead of being installed into site-packages: one file, one
+#: module, loaded at the next start. ``$ZETTCODE_PLUGINS_DIR`` moves it, the way ``$ZETTCODE_CONFIG`` moves the config.
+DEFAULT_PLUGINS_DIR = DEFAULT_STORE.parent / "plugins"
+PLUGINS_DIR_VARIABLE = "ZETTCODE_PLUGINS_DIR"
+
+
+def plugins_dir() -> Path:
+    """Return the folder single-file plugins live in: ``$ZETTCODE_PLUGINS_DIR`` or ``~/.zettcode/plugins``."""
+    override = os.getenv(PLUGINS_DIR_VARIABLE)
+    return Path(override).expanduser() if override else DEFAULT_PLUGINS_DIR
+
+
+#: MCP servers are ZettCode's own file, so they are configured independently of
+#: whatever other zett tools read.
+DEFAULT_MCP_CONFIG = Path.home() / ".zettcode" / "mcp.json"
+
+#: Where the just-in-time harness keeps the tools a model wrote, one folder per session. Beside the sessions, not in
+#: them: it is the model's own code, and clearing or moving the session store should not take it along.
+DEFAULT_HARNESS_DIR = Path.home() / ".zettcode" / "harness"
+
+#: What the background release check leaves behind: the newest version it saw
+#: and the version the reader asked not to hear about again.
+DEFAULT_UPDATE_FILE = Path.home() / ".zettcode" / "update.json"
+
+#: Where the reader's own palettes live: one ``<name>.toml`` each, picked by name with ``/theme <name>``.
+DEFAULT_THEMES_DIR = Path.home() / ".zettcode" / "themes"
+
+#: The one palette file that is laid over whatever theme is in force.
+DEFAULT_THEME_FILE = Path.home() / ".zettcode" / "theme.toml"
+
+#: Where tiktoken keeps the vocabulary it downloads once. Deliberately not the
+#: OS temp directory, which is cleaned whenever the system feels like it: a purge
+#: turns the next token count into a 1.7 MB download, and `/context` waits behind
+#: it. Under this program's own directory the fetch happens once.
+DEFAULT_TOKENIZER_CACHE = Path.home() / ".zettcode" / "cache" / "tiktoken"
+
+#: Anything written to stderr while the TUI owns the screen is kept here: a
+#: child process — an MCP server announcing itself, say — cannot know that the
+#: frame is the interface, and the renderer only repaints what it changed.
+DEFAULT_LOG = Path.home() / ".zettcode" / "log" / "tui.log"
+
+#: The commands typed in the ``/bash`` panel, one per line, so they are there next time.
+DEFAULT_COMMAND_HISTORY = Path.home() / ".zettcode" / "command_history"
+
+
+def config_path(path: str | Path | None = None) -> Path:
+    """Return the config file to read: an explicit path, ``$ZETTCODE_CONFIG``, or the default.
+
+    Here rather than beside the settings it loads because the frame drawn before
+    those settings are read needs to name the same file without importing them.
+    """
+    if path is not None:
+        return Path(path).expanduser()
+    override = os.getenv("ZETTCODE_CONFIG")
+    return Path(override).expanduser() if override else CONFIG_FILE
+
+
+def check_config_path(path: str | Path | None = None) -> Path:
+    """Return the config path, refusing one that exists and is not a file.
+
+    A path that exists and is not a file — a directory from ``ZETTCODE_CONFIG=.``, a FIFO — is a configuration
+    nobody can read, and it is not the fresh machine either: the terminal would start as if nothing were set up
+    and then fail every setting on that path. So is a link whose target is gone, which is not a file for the same
+    reason and would be replaced by the write rather than followed. A path with nothing at it is the fresh machine
+    and is answered with the path as it is.
+
+    Here, beside :func:`config_path`, because the command line asks this before it takes the terminal and before
+    the settings module may be imported at all.
+
+    Args:
+        path: The path to check; ``$ZETTCODE_CONFIG`` or ``~/.zettcode/config.toml`` by default.
+
+    Raises:
+        ValueError: The path exists (or is a link) and is not a file.
+    """
+    source = config_path(path)
+    if not source.is_file() and (source.exists() or source.is_symlink()):
+        raise ValueError(f"{source} is not a file, so there is nothing to read there")
+    return source
+
+
+def resume_command(session_id: str, workspace: Path) -> str:
+    """Return the command that reopens one stored session from anywhere.
+
+    It is written down once because two places say it: the line printed on the way
+    out, and the line a fork leaves in the conversation. The workspace is part of it
+    because the store is keyed by workspace — the same id means nothing in another
+    checkout — and it is quoted, because a path may hold a space.
+    """
+    return f"zettcode resume {shlex.quote(session_id)} --workspace {shlex.quote(str(workspace))}"

zettcode/plugin_tui.py

@@ -0,0 +1,133 @@
+"""The interface of ``ctx.tui``: what a plugin may register when the process has a screen.
+
+The terminal's group implements this; the context is typed with it so a plugin author sees the surface from the type
+checker, and the guard ``if ctx.tui is None`` narrows it. It lives here, in a leaf module both layers may import, so the
+engine can name it without importing the terminal — and the terminal can implement it without the engine importing the
+terminal's own types.
+
+The parameter types are deliberately loose: a command handler, a theme, a pet, a presenter and a row builder are the
+terminal's own classes, which this module does not import. The docstrings say what each argument is, and
+:class:`zettcode.app.plugins.groups.TuiGroups` is the implementation that takes the real ones.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+__all__ = ["TuiGroup"]
+
+
+class TuiGroup(ABC):
+    """What only the terminal can hold, as ``ctx.tui``.
+
+    A process without a screen has ``ctx.tui is None``; a plugin that only adds these starts its ``activate`` with
+    ``if ctx.tui is None: return``.
+    """
+
+    @property
+    @abstractmethod
+    def registered_commands(self) -> Any:
+        """Return the commands registered so far, in registration order."""
+
+    @property
+    @abstractmethod
+    def themes(self) -> Any:
+        """Return the palettes registered so far, in registration order."""
+
+    @property
+    @abstractmethod
+    def pets(self) -> Any:
+        """Return the pets registered so far, in registration order."""
+
+    @property
+    @abstractmethod
+    def presenters(self) -> Any:
+        """Return the presenters registered so far, in registration order."""
+
+    @property
+    @abstractmethod
+    def turn_segments(self) -> Any:
+        """Return the items of the line a request ends on, in the order they stand."""
+
+    @abstractmethod
+    def register_command(
+        self,
+        name: str,
+        description: str,
+        handler: Any,
+        *,
+        when_busy: str = "refuse",
+        subcommands: Any = (),
+    ) -> Any:
+        """Add a command that may open a page, ask the shell to act, or wait for a request to end.
+
+        ``handler`` is called with a :class:`~zettcode.app.commands.CommandContext` and returns a
+        :class:`~zettcode.app.commands.CommandResult`. A command whose whole answer is text belongs on
+        ``ctx.commands`` instead, where a process without a screen can run it too.
+        """
+
+    @abstractmethod
+    def register_command_provider(self, provider: Any) -> Any:
+        """Add commands that are worked out when the menu is built, from the current state."""
+
+    @abstractmethod
+    def register_theme(self, name: str, theme: Any, *, description: Any = "") -> Any:
+        """Offer a palette under its name; ``/theme`` lists, previews and switches to it."""
+
+    @abstractmethod
+    def register_pet(self, name: str, pet: Any, *, description: Any = "") -> Any:
+        """Offer a companion under its name; ``/pet`` lists, previews and switches to it."""
+
+    @abstractmethod
+    def register_presenter(self, presenter: Any) -> Any:
+        """Draw a kind of entry, or one family inside a kind, instead of the way it is drawn now."""
+
+    @abstractmethod
+    def register_header_left(self, builder: Any, *, name: str = "", override: bool = False) -> tuple[Any, bool]:
+        """Draw a segment on the header's left side."""
+
+    @abstractmethod
+    def register_header_right(self, builder: Any, *, name: str = "", override: bool = False) -> tuple[Any, bool]:
+        """Draw a segment on the header's right side."""
+
+    @abstractmethod
+    def register_status_left(self, builder: Any, *, name: str = "", override: bool = False) -> tuple[Any, bool]:
+        """Draw a segment on the status line's left side."""
+
+    @abstractmethod
+    def register_status_right(self, builder: Any, *, name: str = "", override: bool = False) -> tuple[Any, bool]:
+        """Draw a segment on the status line's right side."""
+
+    @abstractmethod
+    def register_turn_segment(self, name: str, summary: str, builder: Any) -> Any:
+        """Add one item to the line a request ends on."""
+
+    @abstractmethod
+    def register_focus_handler(self, handler: Any) -> Any:
+        """Be told when the terminal window gains or loses focus: ``handler(focused: bool)``.
+
+        The terminal asks for focus reports (DECSET 1004) when it starts, so a plugin can tell a reader who stepped
+        away from one who is watching — which is what a recap, a notification or a pause waits for. A terminal that
+        does not report focus never calls it, and nothing else changes.
+        """
+
+    @abstractmethod
+    def register_turn_start_handler(self, handler: Any) -> Any:
+        """Be told when a turn of the conversation starts: ``handler()``, before the request is sent.
+
+        The counterpart of :meth:`register_turn_end_handler`, and what makes an idle wait possible: work that waits
+        for the reader to stop asking cancels on the start and is armed by the end. A side question and a resumed
+        request are not turns; a turn a command starts with ``host.prompt`` is.
+        """
+
+    @abstractmethod
+    def register_turn_end_handler(self, handler: Any) -> Any:
+        """Be told when a turn of the conversation ends: ``handler(completed: bool)``, after the row it ended on.
+
+        ``completed`` is false for a turn that was stopped or that failed; both are ends, and a plugin that only
+        cares about answered requests tests it. A request the reader sent is a turn, and so is one a command started
+        with ``host.prompt``; running a command is not itself a turn, and neither is a side question or a resume. It is
+        called from inside the run that just ended, before the shell is free again, and nothing guards two turns at
+        once: a handler that starts work schedules it instead of running a turn from there.
+        """