zettcode-jit-harness 0.4.1__py3-none-any.whl

zettcode/jit_harness/__init__.py

@@ -0,0 +1,15 @@
+"""The just-in-time harness of ZettCode: the plugin, the switchable extension, and the screen the reader opens.
+
+A part of the program that lives in a distribution of its own, found through the ``zettcode.agent`` entry point.
+``[harness] jit`` in the configuration is what turns it on. The extension (:mod:`zettcode.jit_harness.extension`)
+imports the framework's harness, so nothing here imports it until the agent is built. The part also owns the read-only
+page ``/harness`` opens (:mod:`zettcode.jit_harness.page`) and the command that opens it
+(:mod:`zettcode.jit_harness.command`), each drawn on the widget framework and the plugin contract alone; the command is
+registered by the plugin, and only where there is a screen.
+"""
+
+from __future__ import annotations
+
+from .plugin import Harness
+
+__all__ = ["Harness"]

zettcode/jit_harness/command.py

@@ -0,0 +1,93 @@
+"""The ``/harness`` command: a read-only panel on the just-in-time harness, shipped with the harness itself.
+
+The command used to live with the shell's own commands, which meant the screen it opens belonged to one distribution
+and the command to another. Both are here now: the part owns what it shows and the way to see it. It is written
+against the plugin contract — the context, the result and ``bottom_panel`` — so the panel is drawn without the
+application, and the SDK is only what ``host.client`` is typed as.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from zettcode.engine.harness_paths import session_directory
+from zettcode.plugin_api.commands import CommandContext, CommandResult
+from zettcode.plugin_api.panels import bottom_panel
+from zettcode.plugin_api.plugin import TuiPlugin
+
+from .page import HARNESS_ROWS, HarnessPage
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zettcode.engine.plugins.context import PluginContext
+
+
+class HarnessCommand(TuiPlugin):
+    """``/harness``: what the harness is doing now, where its files are, and what the model has written."""
+
+    name = "harness-command"
+    description = "the just-in-time harness's state and this session's repositories"
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Register ``/harness``; it opens a page, so it is refused while a request runs rather than opened over it.
+
+        Reading the files costs nothing, and a command that only reports may run beside a request (``/context``
+        does); this one draws a panel over the conversation, which is why it waits for the request to end.
+        """
+        if ctx.tui is None:
+            return
+        ctx.tui.register_command(
+            "harness",
+            "what the just-in-time harness is doing, and where its tools are",
+            self.harness,
+            when_busy="refuse",
+        )
+
+    async def harness(self, context: CommandContext) -> CommandResult:
+        """Open a read-only panel on the just-in-time harness.
+
+        The switch is a plugin setting now: `/plugins` turns the harness on or off for the next start, and this page
+        says which state it found, where the repositories live, and what this session has written. Nothing on the
+        page changes anything; the repositories are read with
+        :func:`zett_agent.jit_harness.inspect_repository`, which imports nothing.
+        """
+        host = context.require_host()
+        if context.argument.strip():
+            return CommandResult(
+                message="/harness no longer takes on or off; /plugins switches the harness, and /harness shows it."
+            )
+        directory = session_directory(host.client.config, host.client.session.id)
+        state = "on" if host.client.harness else "off"
+        repositories = self._repositories(directory)
+        page = HarnessPage(state=state, directory=directory, repositories=repositories, on_close=host.close_page)
+        return CommandResult(widget=bottom_panel(page, rows=HARNESS_ROWS))
+
+    def _repositories(self, directory: Path) -> list[tuple[str, str]]:
+        """Return this session's repositories as ``(name, detail)``: what the files declare, or why they cannot load."""
+        from zett_agent.jit_harness import inspect_repository
+
+        try:
+            found = (
+                sorted(path for path in directory.iterdir() if (path / "__init__.py").is_file())
+                if directory.is_dir()
+                else []
+            )
+        except OSError as error:
+            return [("Could not be read", str(error))]
+        rows: list[tuple[str, str]] = []
+        for path in found:
+            policy = inspect_repository(path)
+            if not policy.ok or policy.manifest is None:
+                rows.append((path.name, f"cannot load: {'; '.join(policy.problems)}"))
+                continue
+            manifest = policy.manifest
+            declared = (
+                f"declares {len(manifest.tools)} tool{'s' if len(manifest.tools) != 1 else ''}"
+                if manifest.tools
+                else "declares no tools"
+            )
+            banned = f"; {len(policy.banned)} banned" if policy.banned else ""
+            rows.append(
+                (path.name, f"{manifest.name} {manifest.version} — {manifest.description} ({declared}{banned})")
+            )
+        return rows

zettcode/jit_harness/extension.py

@@ -0,0 +1,208 @@
+"""The just-in-time harness, kept behind a switch the reader can flip between two requests.
+
+The framework's :class:`~zett_agent.jit_harness.JITHarnessExtension` lets the model write small Python tools of its
+own and run them. That is opt-in by nature, and it is not behind the shell's permission level by itself: the plugin
+puts a child process (and, below `full`, a sandbox) between that code and this window. So it is registered always and
+does nothing until switched on, which is what lets the ``/plugins`` switch take effect on the next start without rebuilding
+the client.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from zett_agent.agent import AgentRunContext
+from zett_agent.events import AgentEvent, AgentEventType
+from zett_agent.extensions.base import ModelRequestNext, ToolCallNext
+from zett_agent.jit_harness import JITHarnessExtension
+from zett_agent.messages import ToolCall, ToolMessage
+from zett_agent.model import ModelEvent, ModelRequest
+from zett_agent.tools.base import ToolResult
+
+from zettcode.engine.extensions.harness_switch import HarnessSwitch
+from zettcode.engine.extensions.mcp_notice import HARNESS_NOTICE_EVENT_NAME, notice_payload
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zett_agent.jit_harness import JITToolHost
+
+__all__ = ["SwitchedHarness"]
+
+
+class SwitchedHarness(JITHarnessExtension):
+    """The framework's harness, inert while its switch is off.
+
+    Every hook that changes a request first asks the switch. A hook that only releases what a request held is left
+    alone, so a request that began with the harness on still lets go of it cleanly. The switch is read once per
+    request, in ``on_tool``, because ``/harness`` waits for an idle shell: no request sees it change halfway.
+    """
+
+    def __init__(
+        self,
+        root: str | Path,
+        switch: HarnessSwitch,
+        *,
+        host_factory: Callable[[], JITToolHost] | None = None,
+        boundary: Callable[[], str] | None = None,
+        unbounded: Callable[[], bool] | None = None,
+        legacy_root: str | Path | None = None,
+    ) -> None:
+        """Keep each session's repository under ``root``, and follow ``switch``.
+
+        Args:
+            root: Directory that holds one subdirectory per session.
+            switch: Whether the harness is on for a request.
+            host_factory: Where a session's repository code runs, called once per session; ``None`` keeps the
+                framework's default, which imports it here. The plugin passes one that puts a child process between
+                the model's code and this window, inside a sandbox unless the reader gave the model everything.
+            boundary: What the host was built for — the shell level, in the plugin's words — read once per request.
+                A session's host is made once, so a level that changed since it was built (``/permission full``
+                while code was already running under a sandbox) would otherwise leave the old answer in force.
+                When it differs, the session is forgotten, which closes its child and builds the next host for the
+                level now in force.
+            unbounded: Whether the level in force promises a boundary this machine does not have. The code the model
+                wrote then runs with the reader's own access, which they are told once per session.
+            legacy_root: The root from before the workspace level, whose session directory is moved under ``root``
+                the first time that session asks for it.
+        """
+        super().__init__(root, host_factory=host_factory)
+        self._root = Path(root)
+        self._legacy_root = Path(legacy_root) if legacy_root is not None else None
+        self._switch = switch
+        self._boundary = boundary
+        self._unbounded = unbounded
+        #: Sessions already told that their repository code has no boundary on this machine.
+        self._said_unbounded: set[str] = set()
+        #: The boundary each session's host was built for, so a change of level is noticed.
+        self._built: dict[str, str] = {}
+        #: Sessions whose child must be closed once the request in flight lets go of them.
+        self._pending: set[str] = set()
+        #: Sessions whose current request has the harness, set by ``on_tool`` and cleared when it is released.
+        self._engaged: set[str] = set()
+
+    def engaged(self, context: AgentRunContext) -> bool:
+        """Return whether this request was given the harness."""
+        return context.session_id in self._engaged
+
+    async def on_tool(self, context: AgentRunContext) -> None:
+        """Mount the harness's tools, when it is on — in a host built for the level in force now."""
+        if self._legacy_root is not None:
+            from zettcode.engine.harness_paths import move_session
+
+            move_session(self._legacy_root, self._root, context.session_id)
+        if not self._switch.on:
+            return
+        self._follow_boundary(context.session_id)
+        self._engaged.add(context.session_id)
+        await self._say_unbounded(context)
+        await super().on_tool(context)
+
+    async def _say_unbounded(self, context: AgentRunContext) -> None:
+        """Tell the reader, once per session, that this machine cannot bound the code the model writes.
+
+        A machine with no sandbox passes ``None`` to the host, which runs the child with the reader's own access. The
+        harness says so because the model's own tools are not a shell command and none of the shell's fallbacks apply
+        to them. A line of news must never be what stops a request, so a failure to publish it is dropped.
+        """
+        if self._unbounded is None or not self._unbounded() or context.session_id in self._said_unbounded:
+            return
+        try:
+            await context.emit(
+                AgentEvent(
+                    type=AgentEventType.CUSTOM,
+                    session_id=context.session_id,
+                    name=HARNESS_NOTICE_EVENT_NAME,
+                    payload=notice_payload(
+                        "this machine has no sandbox, so the tools the model writes run with your own access; "
+                        "`/plugins` turns the harness plugin off",
+                        "warn",
+                    ),
+                )
+            )
+        except Exception:  # noqa: BLE001 - news is never what stops a request
+            return
+        self._said_unbounded.add(context.session_id)
+
+    def _follow_boundary(self, session_id: str) -> None:
+        """Forget a session whose host was built for a boundary that is no longer in force."""
+        if self._boundary is None:
+            return
+        now = self._boundary()
+        built = self._built.get(session_id)
+        if built is None:
+            self._built[session_id] = now
+            return
+        if built == now:
+            return
+        # Its child was started without (or with) a boundary the reader has since changed: close it, and let the next
+        # request build the host the boundary asks for. A fail-open sandbox is the case that matters. The new value is
+        # recorded only once the old child is really gone, so a forget that had to wait is tried again next time.
+        if self._forget(session_id):
+            self._built[session_id] = now
+        else:
+            self._pending.add(session_id)
+
+    def _forget(self, session_id: str) -> bool:
+        """Close a session's child now, or say that the request in flight still holds it."""
+        try:
+            self.forget_session(session_id)
+        except KeyError:
+            # The framework dropped it already (an idle session past its cap): nothing is left to close, and nothing
+            # that is keyed by it is worth keeping either.
+            self._drop(session_id)
+            return True
+        except RuntimeError:
+            return False
+        self._drop(session_id)
+        return True
+
+    def _drop(self, session_id: str) -> None:
+        """Forget what this window remembered about a session the framework no longer holds."""
+        self._built.pop(session_id, None)
+        self._said_unbounded.discard(session_id)
+
+    async def on_state(self, context: AgentRunContext) -> None:
+        """Adopt late tool registrations, for a request that has the harness."""
+        if self.engaged(context):
+            await super().on_state(context)
+
+    async def on_tool_call(self, context: AgentRunContext, call: ToolCall, call_next: ToolCallNext) -> ToolResult:
+        """Run a call through the harness when it is engaged, and straight through when not."""
+        if not self.engaged(context):
+            return await call_next()
+        return await super().on_tool_call(context, call, call_next)
+
+    async def before_tool(self, context: AgentRunContext, call: ToolCall) -> None:
+        """Announce a harness tool call, when engaged."""
+        if self.engaged(context):
+            await super().before_tool(context, call)
+
+    async def after_tool(
+        self, context: AgentRunContext, call: ToolCall, result: ToolMessage, error: Exception | None
+    ) -> None:
+        """Report a harness tool call's outcome, when engaged."""
+        if self.engaged(context):
+            await super().after_tool(context, call, result, error)
+
+    async def on_model_request(
+        self, context: AgentRunContext, request: ModelRequest, call_next: ModelRequestNext
+    ) -> AsyncIterator[ModelEvent]:
+        """Add the harness's guidance to the request, when engaged; leave it untouched when not."""
+        if not self.engaged(context):
+            async for event in call_next(request):
+                yield event
+            return
+        async for event in super().on_model_request(context, request, call_next):
+            yield event
+
+    def _release(self, context: AgentRunContext) -> None:
+        """Let go of what the request held, and forget that it had the harness."""
+        self._engaged.discard(context.session_id)
+        # Detach first: the framework refuses to forget a session an active request still holds, and the release is
+        # what makes it idle. Only then can the child built for the old boundary be closed.
+        super()._release(context)
+        if context.session_id in self._pending:
+            self._pending.discard(context.session_id)
+            if self._forget(context.session_id) and self._boundary is not None:
+                self._built[context.session_id] = self._boundary()

zettcode/jit_harness/page.py

@@ -0,0 +1,58 @@
+"""The read-only panel `/harness` opens: the switch's state, the folder, and this session's repositories."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from zettcode.tui import ListItem, ListPage
+
+#: Rows the panel asks for when it is anchored to the bottom edge.
+HARNESS_ROWS = 12
+
+
+def _shown(directory: Path) -> str:
+    """Return the folder as the subtitle shows it: the whole path, with the home directory collapsed to ``~``.
+
+    The panel has the width of the screen, so unlike the header it does not shorten the tail; the one substitution is
+    the home directory, which is longer than it says.
+    """
+    value = str(directory)
+    home = str(Path.home())
+    if value == home or value.startswith(home + "/"):
+        return "~" + value[len(home) :]
+    return value
+
+
+class HarnessPage(ListPage):
+    """What the harness is doing now: on or off, where its files are, and what the model has written.
+
+    The page writes nothing: the switch lives on the `/plugins` page, which is where a reader turns the harness on or
+    off for the next start. Each repository is one row; selecting any row (or Escape) closes the page.
+    """
+
+    def __init__(
+        self,
+        *,
+        state: str,
+        directory: Path,
+        repositories: Sequence[tuple[str, str]],
+        on_close: Callable[[], None],
+    ) -> None:
+        items = [ListItem(name, name, detail) for name, detail in repositories]
+        if not items:
+            items = [
+                ListItem(
+                    "none",
+                    "No repositories yet",
+                    "the model makes one with repo_create when the harness is on",
+                )
+            ]
+        super().__init__(
+            items,
+            title=f"Harness is {state}",
+            subtitle=_shown(directory),
+            footer="/plugins switches it \u00b7 esc close",
+            on_select=lambda _value: on_close(),
+            on_cancel=on_close,
+        )

zettcode/jit_harness/plugin.py

@@ -0,0 +1,84 @@
+"""The plugin that hands the agent the just-in-time harness."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zettcode.engine.extensions.harness_switch import HarnessSwitch
+from zettcode.engine.permission import ShellPolicy
+from zettcode.engine.plugins.plugin import Plugin, PluginSetting
+from zettcode.engine.plugins.services import HARNESS, POLICY
+from zettcode.plugin_api.host import HOST_LINK, HostLink
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zett_agent.extensions.base import AgentExtension
+    from zett_agent.jit_harness import JITToolHost
+
+    from zettcode.engine.plugins.context import PluginContext
+    from zettcode.engine.plugins.state import AgentBuild
+
+
+class Harness(Plugin):
+    """The just-in-time harness: the model keeps small Python tools of its own, when the reader has it on.
+
+    The extension is always registered and inert until the switch is on, so a switch written by ``/plugins`` reaches the
+    next request of a client that was already built. Each session keeps its tools in its own folder under
+    ``config.harness_dir``, which is ``~/.zettcode/harness`` unless the configuration object says otherwise. The page
+    ``/harness`` opens (:mod:`.page`) and the command that opens it (:mod:`.command`) ship with the part; the command
+    is registered here, only for a process that has a screen and the shell's link, so the SDK and the server hold
+    nothing of the terminal.
+    """
+
+    name = "harness"
+    description = "The just-in-time tool harness, off by default"
+    setting = PluginSetting("jit_harness", "harness", "jit")
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Register the switchable extension; the framework's harness is imported when the agent is built."""
+        from zettcode.engine.harness_paths import harness_root
+
+        switch = ctx.service(HARNESS, HarnessSwitch)
+        root = harness_root(ctx.config)
+        policy = ctx.service(POLICY, ShellPolicy)
+
+        def host() -> JITToolHost:
+            """Where one session's repository code runs.
+
+            A child process either way, so a crash, a hang or a runaway allocation in code the model wrote stays
+            out of this window. The boundary comes from the policy — none at `full`, the boundary `safe` uses below
+            it — and `None` on a machine that has no sandbox.
+            """
+            from zett_agent.jit_harness import SubprocessToolHost
+
+            return SubprocessToolHost(sandbox=policy.jit_sandbox())
+
+        def boundary() -> str:
+            """What a session's child was built around: the sandbox itself, or none.
+
+            The *level* is not the key. `ask` and `safe` hand the harness the same sandbox, and restarting a child for
+            nothing costs the model its loaded repository — the next tool call fails until it is loaded again — so this
+            changes only when the boundary does.
+            """
+            sandbox = policy.jit_sandbox()
+            return "none" if sandbox is None else type(sandbox).__name__ + str(id(sandbox))
+
+        def build(_: AgentBuild) -> AgentExtension:
+            from .extension import SwitchedHarness
+
+            return SwitchedHarness(
+                root,
+                switch,
+                host_factory=host,
+                boundary=boundary,
+                unbounded=policy.sandbox_missing,
+                legacy_root=ctx.config.harness_dir,
+            )
+
+        ctx.agent.register_extension_factory("SwitchedHarness", build)
+
+        # The page and the command that opens it are this part's; only a terminal can hold a command, and only the
+        # shell attaches the link a command runs against, so a process without a screen registers nothing here.
+        if ctx.tui is not None and ctx.find(HOST_LINK, HostLink) is not None:
+            from .command import HarnessCommand
+
+            HarnessCommand().activate(ctx)

zettcode_jit_harness-0.4.1.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: zettcode-jit-harness
+Version: 0.4.1
+Summary: The just-in-time tool harness of ZettCode: its extension, its page and the command that opens it
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,harness,zettcode
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zett-agent<0.3,>=0.2.7
+Requires-Dist: zettcode-engine
+Requires-Dist: zettcode-plugin-api
+Requires-Dist: zettcode-tui

zettcode_jit_harness-0.4.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+zettcode/jit_harness/__init__.py,sha256=gXGDEvWL6jdv4QV2w69dG2Ml9yuI3KLmCprHMjeoLow,820
+zettcode/jit_harness/command.py,sha256=Y_QwMjhi3QI1hpqMlQTG9uFP94EUXyvuYEPqlmOZQrQ,4407
+zettcode/jit_harness/extension.py,sha256=cFWfPuwxRChHpBMMveKmZR-6Asl5UgGh6cTKo-J6bdI,10582
+zettcode/jit_harness/page.py,sha256=ujBTyXgmgNsxBchbo220MmnJyz-Sud_3EhXXxSGO7JU,2012
+zettcode/jit_harness/plugin.py,sha256=pXbleP0Y9D-KrB4ClfHGrb1oHOL_c0T66JoX9na_hyY,3934
+zettcode/jit_harness/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zettcode_jit_harness-0.4.1.dist-info/METADATA,sha256=3Tvc-UKMVdDW3WDnOH1ua3SW0o45wYFbvfNHxlu_F5s,860
+zettcode_jit_harness-0.4.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zettcode_jit_harness-0.4.1.dist-info/entry_points.txt,sha256=dBHokz-z1rYKvIYdYW_Z-zThI3oBA7BCyhBbQdqxGiY,63
+zettcode_jit_harness-0.4.1.dist-info/RECORD,,

zettcode_jit_harness-0.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zettcode_jit_harness-0.4.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[zettcode.agent]
+harness = zettcode.jit_harness.plugin:Harness