zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/permission/sandbox.py

@@ -0,0 +1,140 @@
+"""The operating-system sandbox a shell command runs in at the ``safe`` level.
+
+``safe`` is the middle rung between asking about everything and running everything: a command runs without a
+question, and what it can do is bounded by the kernel and not by anybody's reading of the command line. The
+boundary is the one Codex draws for its workspace-write mode:
+
+* it may write the workspace, and the system temporary directory (``/tmp`` and ``$TMPDIR``), and nothing else;
+* it may read the rest of the machine, except the places credentials live (``~/.ssh``, ``~/.aws`` and the like);
+* it has no network, unless the configuration says ``[shell] network = true``;
+* the files that run code later outside it (``.git/hooks``, ``.git/config``, shell start-up files) stay read-only
+  even inside the workspace.
+
+The enforcement is ``zett-agent``'s: Seatbelt (``sandbox-exec``) on macOS and bubblewrap on Linux. Windows has
+none, and neither has a Linux machine without ``bwrap``; there :attr:`ShellSandbox.available` is false and the
+policy falls back to what ``safe`` was before the sandbox existed (read-only commands run, the rest ask), so the
+word never promises a boundary the machine cannot draw.
+
+The sandbox does not run the command. It rewrites it into one that starts under the sandbox's launcher, which the
+shell tool then runs the way it runs any command, so the output handling, the timeout and the process-group kill
+stay the framework's.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+import tempfile
+from pathlib import Path
+
+from zett_agent.sandbox import NetworkMode, SandboxPolicy, SandboxUnavailableError, create_sandbox
+from zett_agent.sandbox.base import Sandbox
+
+from ..tools.boundary import Sandboxer
+
+__all__ = ["ShellSandbox", "SANDBOX_HINT", "temporary_roots"]
+
+#: Appended to the failure of a command that ran sandboxed, so the model learns the boundary instead of
+#: retrying the same call: a denied write and a missing network look like a bare "Operation not permitted".
+SANDBOX_HINT = (
+    "[sandbox] This command ran in the `safe` sandbox: it can write only the workspace and the temporary "
+    "directory{network}. If it failed for that reason, tell the user which command needs more and let them "
+    "choose /permission full."
+)
+
+
+def temporary_roots() -> tuple[Path, ...]:
+    """Return the temporary directories a sandboxed command may write: ``/tmp`` and the process's own.
+
+    On macOS these are different places (``/tmp`` is ``/private/tmp``, and ``$TMPDIR`` is under
+    ``/var/folders``); on Linux they usually coincide. Only directories that exist are returned.
+    """
+    candidates = [Path("/tmp"), Path(tempfile.gettempdir())]
+    found: list[Path] = []
+    for path in candidates:
+        if path.is_dir() and path not in found:
+            found.append(path)
+    return tuple(found)
+
+
+class ShellSandbox(Sandboxer):
+    """The sandbox for one workspace: whether this machine has one, and a command rewritten to run in it."""
+
+    def __init__(self, workspace: Path, *, network: bool = False) -> None:
+        """Describe the boundary; nothing is probed until :attr:`available` is first read.
+
+        Args:
+            workspace: The directory commands run in, which they may write.
+            network: Whether a sandboxed command may use the network.
+        """
+        self.workspace = workspace
+        self.network = network
+        self._sandbox: Sandbox | None = None
+        self._reason: str | None = None
+        self._probed = False
+
+    def _probe(self) -> None:
+        """Build the sandbox once and remember why not when the machine cannot."""
+        if self._probed:
+            return
+        self._probed = True
+        if not (sys.platform == "darwin" or sys.platform.startswith("linux")):
+            self._reason = "this platform has no sandbox; commands at `safe` are limited to read-only ones"
+            return
+        policy = SandboxPolicy.workspace_write(
+            self.workspace,
+            *temporary_roots(),
+            network=NetworkMode.FULL if self.network else NetworkMode.NONE,
+        )
+        try:
+            self._sandbox = create_sandbox(policy, require_isolation=True)
+        except SandboxUnavailableError as error:
+            self._reason = str(error)
+
+    @property
+    def available(self) -> bool:
+        """Return whether this machine can sandbox a command."""
+        self._probe()
+        return self._sandbox is not None
+
+    @property
+    def boundary(self) -> Sandbox | None:
+        """Return the sandbox itself, or ``None`` when this machine has none.
+
+        For a caller that runs code *inside* one rather than rewriting a command into it: the harness starts a
+        child process for the model's own tools, and at `safe` that child runs in this boundary.
+        """
+        self._probe()
+        return self._sandbox
+
+    @property
+    def unavailable_reason(self) -> str | None:
+        """Return why there is no sandbox, or ``None`` when there is one."""
+        self._probe()
+        return self._reason
+
+    def wrap(self, command: str, cwd: Path | None = None) -> str:
+        """Return ``command`` as a shell line that runs it inside the sandbox, in ``cwd``.
+
+        The environment the sandbox allows (no API keys or tokens) is spelled out with ``env -i``, because the
+        shell tool starts the line with the host's own environment.
+
+        ``cwd`` is where the command is meant to run — the tool's ``work_dir``, or the workspace. A Linux sandbox
+        puts ``--chdir`` in the argv it returns, and that wins over the ``cwd=`` of the spawn, so passing the
+        workspace for a command that runs somewhere else would run it in the wrong directory without a word. A
+        directory outside the workspace is outside the policy the sandbox writes, and the command will fail there
+        rather than be let out of it.
+
+        Raises:
+            RuntimeError: The machine has no sandbox; check :attr:`available` first.
+        """
+        self._probe()
+        if self._sandbox is None:
+            raise RuntimeError(self._reason or "no sandbox")
+        wrapped = self._sandbox.wrap(command, cwd=cwd if cwd is not None else Path.cwd())
+        assignments = [f"{name}={value}" for name, value in wrapped.env.items()]
+        return shlex.join(["env", "-i", *assignments, *wrapped.argv])
+
+    def hint(self) -> str:
+        """Return the note that goes after a failed sandboxed command."""
+        return SANDBOX_HINT.format(network="" if self.network else " and has no network")

zettcode/engine/pipeline.py

@@ -0,0 +1,191 @@
+"""Work that must not hold the process, on threads nobody joins.
+
+A launch is often abandoned before its first turn — read the screen, quit — and
+what it was warming must not hold that exit open. What decides that is the kind
+of thread the work runs on: the default executor's threads are joined while the
+interpreter shuts down, so anything still in flight delays the process by its
+whole duration — about a second for the model SDKs, seconds for a download —
+while a daemon thread is left behind and the same exit takes milliseconds.
+Neither leaves anything on stderr on the versions this project runs.
+
+Two shapes of it live here: :class:`ImportPipeline`, for the modules a launch
+wants before the first turn, and :class:`DaemonCall`, for one callable whose
+answer may arrive after whoever asked for it has gone. Nothing is wasted either
+way: what finished is a cache hit for the work that comes later, and what did not
+is what that work would have paid anyway, done while the reader is reading the
+first screen — a pipeline filling behind an instruction.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import threading
+from collections.abc import Callable, Sequence
+from typing import Generic, TypeVar
+
+
+class ImportPipeline:
+    """Import a list of modules, in order, on a daemon thread.
+
+    Args:
+        names: Dotted module names, imported in this order. A name that cannot be
+            imported is recorded in :attr:`failures` and the list carries on: a
+            module that is missing here is reported where it is actually used,
+            which is where a reader can act on it.
+
+    Note:
+        :meth:`start` returns without waiting for anything, and nothing else
+        waits for the thread either — a process that ends mid-list ends at once.
+        :meth:`wait` is for the code that needs the modules now, on the thread
+        that needs them.
+    """
+
+    def __init__(self, names: Sequence[str]) -> None:
+        """Hold the list; nothing starts until :meth:`start`."""
+        self._names = tuple(names)
+        self._finished = threading.Event()
+        self._stopped = threading.Event()
+        self._on_finish: Callable[[], None] | None = None
+        self._thread: threading.Thread | None = None
+        #: Modules that could not be imported, and why, keyed by module name.
+        self.failures: dict[str, BaseException] = {}
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        """Return the modules this pipeline imports, in order."""
+        return self._names
+
+    @property
+    def done(self) -> bool:
+        """Return whether the list was worked through, or given up on."""
+        return self._finished.is_set()
+
+    def start(self, *, on_finish: Callable[[], None] | None = None) -> None:
+        """Begin importing, and return without waiting for any of it.
+
+        Args:
+            on_finish: Called on the pipeline's thread once the list is done or
+                given up on, so a caller can release whoever is waiting. It runs
+                off the event loop and must not touch it directly; a loop that
+                has closed in the meantime is not an error.
+        """
+        if self._thread is not None:
+            return
+        self._on_finish = on_finish
+        self._thread = threading.Thread(target=self._run, name="zettcode-imports", daemon=True)
+        self._thread.start()
+
+    def wait(self, timeout: float | None = None) -> bool:
+        """Block until the list is done, and report whether it finished in time."""
+        return self._finished.wait(timeout)
+
+    def stop(self) -> None:
+        """Ask the thread to give up at the next module boundary, and release waiters.
+
+        Called when the work is no longer wanted — the shell is going away and
+        the imports were for a turn that will not happen. The module being
+        imported is not interrupted, so the thread is never cut in half by this;
+        it notices between one module and the next.
+        """
+        self._stopped.set()
+        self._finished.set()
+        self._notify()
+
+    def _run(self) -> None:
+        try:
+            for name in self._names:
+                if self._stopped.is_set():
+                    break
+                try:
+                    importlib.import_module(name)
+                except Exception as error:
+                    # A failure here has no reader: the module is reported by
+                    # whatever needed it, which can say what it was doing.
+                    self.failures[name] = error
+        finally:
+            self._finished.set()
+            self._notify()
+
+    def _notify(self) -> None:
+        """Tell the caller the list is over, from the pipeline's own thread."""
+        if self._on_finish is None:
+            return
+        try:
+            self._on_finish()
+        except RuntimeError:
+            # The loop this was reporting to closed while the imports ran: the
+            # shell that asked for them has already gone, and nobody is waiting.
+            pass
+
+
+#: The value a callable hands back, of whatever type it is.
+T = TypeVar("T")
+
+
+class DaemonCall(Generic[T]):
+    """Run one callable on a daemon thread, and wait for it without owning it.
+
+    ``asyncio.to_thread`` does the same work, but its thread belongs to the
+    interpreter's default executor, which is joined while the process shuts down:
+    a call still running when the shell leaves delays the exit by its whole
+    duration. Here the thread is a daemon and the signal is an event, so
+    abandoning the call costs nothing — the answer is simply dropped, or picked
+    up later by :meth:`peek` if it arrived after all.
+
+    Args:
+        action: Called on the thread; its return value is what :meth:`wait`
+            answers.
+    """
+
+    def __init__(self, action: Callable[[], T]) -> None:
+        """Hold the callable; nothing runs until :meth:`start`."""
+        self._action = action
+        self._thread: threading.Thread | None = None
+        self._done: asyncio.Event | None = None
+        self._result: T | None = None
+        self._error: BaseException | None = None
+
+    @property
+    def started(self) -> bool:
+        """Return whether the call is on a thread."""
+        return self._thread is not None
+
+    def start(self) -> None:
+        """Begin the call and return at once, with the work on another thread."""
+        if self._thread is not None:
+            return
+        loop = asyncio.get_running_loop()
+        self._done = asyncio.Event()
+        self._thread = threading.Thread(target=self._run, args=(loop, self._done), name="zettcode-call", daemon=True)
+        self._thread.start()
+
+    def _run(self, loop: asyncio.AbstractEventLoop, done: asyncio.Event) -> None:
+        """Do the work, then release whoever waits, from this thread."""
+        try:
+            self._result = self._action()
+        except BaseException as error:  # noqa: BLE001 - an answer of None covers every failure
+            self._error = error
+        finally:
+            try:
+                loop.call_soon_threadsafe(done.set)
+            except RuntimeError:
+                # The loop this was reporting to has closed: the shell that asked
+                # for the call has already gone, and nobody is waiting.
+                pass
+
+    async def wait(self, timeout: float | None = None) -> T | None:
+        """Wait for the answer, and return ``None`` if it failed or came too late."""
+        if self._done is None:
+            raise RuntimeError("DaemonCall.start() has not been called")
+        try:
+            await asyncio.wait_for(self._done.wait(), timeout)
+        except asyncio.TimeoutError:
+            return None
+        return None if self._error is not None else self._result
+
+    def peek(self) -> T | None:
+        """Return the answer if the call has finished, without waiting for it."""
+        if self._done is None or not self._done.is_set() or self._error is not None:
+            return None
+        return self._result

zettcode/engine/plugins/__init__.py

@@ -0,0 +1,72 @@
+"""The engine's plugin support: the base class, the context, the loader, and the switches.
+
+A plugin needs only this package::
+
+    from zettcode.engine.plugins import Plugin, PluginContext
+
+    class Audit(Plugin):
+        name = "audit"
+
+        def activate(self, ctx: PluginContext) -> None:
+            ctx.agent.register_extension(AuditExtension())
+
+What a plugin can register follows from the groups on ``ctx``: :attr:`PluginContext.agent` in every process, and
+:attr:`PluginContext.tui` where the terminal is loading. A plugin that fills a header or status row by overriding a
+hook is a :class:`zettcode.app.plugins.TuiPlugin`, which is this class plus that mixin. The plugins ZettCode composes
+the agent from are not here: they are :data:`zettcode.sdk.builtins.AGENT_PLUGINS`, because they need the broker, the
+config file and the MCP client, which the engine does not carry.
+
+The pieces live in focused modules — :mod:`~zettcode.engine.plugins.mixins` for the hook groups,
+:mod:`~zettcode.engine.plugins.context` for activation, :mod:`~zettcode.engine.plugins.plugin` for the base class, and
+:mod:`~zettcode.engine.plugins.loader` for discovery — and are re-exported here as one surface.
+"""
+
+from __future__ import annotations
+
+from .context import PluginContext
+from .extension import PluginExtension
+from .loader import PLUGIN_ENTRY_POINT_GROUP, Loader, installed_entry_points, load_plugins
+from .mixins import (
+    PluginAgentMixin,
+    PluginEventMixin,
+    PluginMaintenanceMixin,
+    PluginMiddlewareMixin,
+    PluginModelMixin,
+    PluginRunMixin,
+    PluginSetupMixin,
+    PluginToolMixin,
+    PluginTurnMixin,
+)
+from .plugin import Plugin, Plugins, PluginSetting
+from .state import AgentBuild, Contribution, ExtensionFactory
+from .switches import PluginEntry, applied, catalog, off_names, set_enabled, set_many
+
+__all__ = [
+    "PLUGIN_ENTRY_POINT_GROUP",
+    "AgentBuild",
+    "Plugin",
+    "PluginContext",
+    "Contribution",
+    "ExtensionFactory",
+    "Loader",
+    "PluginAgentMixin",
+    "PluginEventMixin",
+    "PluginExtension",
+    "PluginMaintenanceMixin",
+    "PluginMiddlewareMixin",
+    "PluginModelMixin",
+    "PluginRunMixin",
+    "PluginSetupMixin",
+    "PluginToolMixin",
+    "PluginTurnMixin",
+    "Plugins",
+    "PluginEntry",
+    "PluginSetting",
+    "applied",
+    "catalog",
+    "installed_entry_points",
+    "load_plugins",
+    "off_names",
+    "set_enabled",
+    "set_many",
+]

zettcode/engine/plugins/commands.py

@@ -0,0 +1,152 @@
+"""The commands a plugin may offer that say nothing about a front end.
+
+A plugin registers a *plain* command on :attr:`~zettcode.engine.plugins.context.PluginContext.commands` when the
+result is text: a paragraph to show and a one-line remark, or a request to start a turn. No widget, no page, no question put to a person — those
+belong to the terminal, which registers its own kind of command on ``ctx.tui`` (see
+:class:`zettcode.app.plugins.groups.TuiGroups`). Keeping the two apart is what lets a command be shown by a front end
+that has no terminal: the handler cannot reach for a shell it will not have.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TypeAlias
+
+__all__ = [
+    "CommandGroups",
+    "PlainCommand",
+    "PlainCommandContext",
+    "PlainCommandResult",
+    "PlainHandler",
+    "TextCommandResult",
+    "TurnCommandResult",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class PlainCommandContext:
+    """What a plain command's handler is handed.
+
+    Attributes:
+        argument: The words typed after the command's name.
+        level: The shell level the session is running at (``deny``, ``ask``, ``safe`` or ``full``), filled by the
+            front end that runs the command. A command that decides what to ask the model says it in these terms
+            rather than reaching for a shell it may not have.
+    """
+
+    argument: str = ""
+    level: str = "ask"
+
+
+@dataclass(frozen=True, slots=True)
+class TextCommandResult:
+    """Words: Markdown for the conversation, an optional document, and a one-line remark.
+
+    ``message`` is what the conversation keeps, as before. ``markdown`` is a document for the front end to show on its
+    own — the terminal opens it as a page, the editor as a preview — for an answer too long to sit between two turns
+    or one a reader means to read rather than scroll past. It is a new field and not a new result type, so a front end
+    that predates it still runs the command and still shows ``message``.
+
+    Attributes:
+        message: Markdown added to the conversation.
+        notification: A one-line remark, as a toast.
+        markdown: A Markdown document shown by the front end in its own view; empty when there is none.
+    """
+
+    message: str = ""
+    notification: str = ""
+    markdown: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class TurnCommandResult:
+    """A request to start rather than an answer: the text the model reads, and what the reader sees for it.
+
+    A command that is a preset for a turn — `/code-review` is the first — says so by returning this. The front end
+    that ran the command starts the turn with ``prompt``; ``shown`` is the short form the conversation keeps, which is
+    what the reader typed.
+
+    Attributes:
+        prompt: What the model reads.
+        shown: What the conversation keeps, when it is not ``prompt``.
+        notification: A one-line remark, as a toast.
+        cache: How the turn may use the provider's prompt cache: ``"read"`` for a one-off whose answer nobody will
+            follow, ``"read_write"`` to extend the cached prefix, ``"off"`` for no directive at all. Empty leaves the
+            front end's own default, which is ``"read_write"`` for a turn.
+    """
+
+    prompt: str
+    shown: str = ""
+    notification: str = ""
+    cache: str = ""
+
+
+#: What a plain command's handler answers with. A failure is not a third case: it raises ``ValueError``, which every
+#: front end already reports as the command's error line.
+PlainCommandResult: TypeAlias = TextCommandResult | TurnCommandResult
+
+
+#: A plain command's handler: sync or async, and it never needs a UI.
+PlainHandler: TypeAlias = Callable[[PlainCommandContext], Awaitable[PlainCommandResult] | PlainCommandResult]
+
+
+@dataclass(frozen=True, slots=True)
+class PlainCommand:
+    """One registered plain command: the name typed, the summary shown, and what runs it.
+
+    ``when_busy`` is what a front end does with the command while a request is in flight (``"refuse"``,
+    ``"queue"`` or ``"now"``), and ``subcommands`` are the words it takes first, for a menu that offers them. Both are
+    the shell's vocabulary rather than a second one: a command that a process without a screen runs later should not
+    need a different spelling.
+    """
+
+    name: str
+    summary: str
+    handler: PlainHandler
+    when_busy: str = "refuse"
+    subcommands: tuple[object, ...] = ()
+
+
+class CommandGroups:
+    """The plain commands one plugin offers, kept in registration order and unique by name."""
+
+    def __init__(self) -> None:
+        self._commands: dict[str, PlainCommand] = {}
+
+    @property
+    def commands(self) -> tuple[PlainCommand, ...]:
+        """Return the commands registered so far, in registration order."""
+        return tuple(self._commands.values())
+
+    def register(
+        self,
+        name: str,
+        summary: str,
+        handler: PlainHandler,
+        *,
+        when_busy: str = "refuse",
+        subcommands: tuple[object, ...] = (),
+    ) -> PlainCommand:
+        """Add one command that any front end can run.
+
+        Args:
+            name: The way it is typed, with its leading slash (``"/usage"``).
+            summary: One line for the command list.
+            handler: Runs with a :class:`PlainCommandContext` and returns a :class:`PlainCommandResult`.
+            when_busy: What a front end does when it is typed while a request is in flight.
+            subcommands: The words it takes first, offered by a menu that has one.
+
+        Raises:
+            ValueError: When the name or the summary is blank, or the name is already taken.
+        """
+        command = name.strip()
+        if not command or not command.startswith("/"):
+            raise ValueError(f"A command is typed with a leading slash, not {name!r}")
+        if not summary.strip():
+            raise ValueError(f"Command {command} needs a summary")
+        if command in self._commands:
+            raise ValueError(f"Command already registered: {command}")
+        registered = PlainCommand(command, summary.strip(), handler, when_busy, tuple(subcommands))
+        self._commands[command] = registered
+        return registered