zettcode-tool-output 0.4.1__py3-none-any.whl

zettcode/tool_output/__init__.py

@@ -0,0 +1,12 @@
+"""A shell command's kept output, moved into the session's folder: the plugin that hands it to the agent.
+
+A part of the program that lives in a distribution of its own, found through the ``zettcode.plugin`` entry point.
+The extension (:mod:`zettcode.tool_output.extension`) reads the store the runtime provides under ``persistence``, so
+nothing here builds one; it acts on the ``bash`` tool's result after the tool has run and before it is stored.
+"""
+
+from __future__ import annotations
+
+from .plugin import ToolOutput
+
+__all__ = ["ToolOutput"]

zettcode/tool_output/extension.py

@@ -0,0 +1,150 @@
+"""Keep what a shell command printed out of the reader's workspace.
+
+The ``bash`` tool keeps a command's full output when the preview it returns is cut
+short, so the model can read the rest. It keeps it in a ``.zett-tool-output`` folder *inside the
+directory it runs in* — the reader's own project — and names the files in the text it returns::
+
+    ... [output truncated; full streams kept at .zett-tool-output/shell-ab12cd/stdout.txt and
+    .zett-tool-output/shell-ab12cd/stderr.txt]
+
+That puts files the reader never asked for among their source, where they turn up in a status
+listing, a search, a backup, or a commit. The folder cannot simply be made a link to somewhere
+else, because the tool resolves it and then asks for the result relative to the working
+directory, which a link out of it breaks the moment output is truncated.
+
+What is done here is to deal with the result: after the tool has run and before
+its result is stored or sent anywhere, the folder it named is moved into the session's own folder
+under the store — ``~/.zettcode/sessions/<workspace>/<session>/tool-output/`` — and the paths in
+the text are rewritten to where the files now are. The model reads them with ``read_file`` by
+absolute path, which that tool accepts, so nothing about how it uses them changes; the reader's
+project is left as it was found; and the output goes away with the session it belongs to.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import shutil
+from pathlib import Path, PurePosixPath
+
+from zett_agent.agent import AgentRunContext
+from zett_agent.extensions.base import AgentExtension
+from zett_agent.messages import ToolCall, ToolMessage
+
+from zettcode.engine.storage import KEPT_OUTPUT, SessionStore
+
+#: The tool whose output is moved.
+SHELL_TOOL = "bash"
+
+#: The folder the tool makes inside the directory it runs in. It is written out here, and not imported from the tool,
+#: because the tool's module brings the schema library with it and this one is loaded at start-up; a test holds the two
+#: equal.
+OUTPUT_ROOT = ".zett-tool-output"
+
+#: The note the tool ends its result with when a preview was cut short. It is matched at the very
+#: end of the text and nowhere else: a command can print anything it likes, and a line that merely
+#: looks like this one, earlier in the output, is the command's own and must not be acted on.
+_NOTE = re.compile(r"full streams kept at (?P<out>\S+) and (?P<err>\S+)\]\s*\Z")
+
+
+class ToolOutputExtension(AgentExtension):
+    """Move a shell command's kept output out of the workspace and into the session's folder."""
+
+    def __init__(self, store: SessionStore) -> None:
+        """Keep the store whose session folders the output moves into."""
+        self._store = store
+
+    async def after_tool(
+        self,
+        context: AgentRunContext,
+        call: ToolCall,
+        result: ToolMessage,
+        error: Exception | None,
+    ) -> None:
+        """Rewrite a truncated shell result so its files are in the session's folder.
+
+        Both outcomes carry the note — a command that failed has its output kept the same way —
+        so the result is handled whether or not ``error`` is set. Nothing here may fail a tool
+        call: whatever goes wrong, the result is left as the tool wrote it, and the files stay
+        where the tool put them, which still works.
+        """
+        if call.name != SHELL_TOOL:
+            return
+        try:
+            await self._move_kept_output(context, result)
+        finally:
+            self._tidy()
+
+    async def _move_kept_output(self, context: AgentRunContext, result: ToolMessage) -> None:
+        """Move the output the result's note names, and rewrite the note to say where it went."""
+        if not isinstance(result.content, str):
+            return
+        note = _NOTE.search(result.content)
+        session_id = context.config.session_id
+        if note is None or not isinstance(session_id, str):
+            return
+        moved = await asyncio.to_thread(self._relocate, note.group("out"), note.group("err"), session_id)
+        if moved is None:
+            return
+        text, out, err = result.content, *moved
+        result.content = (
+            text[: note.start("out")] + out + text[note.end("out") : note.start("err")] + err + text[note.end("err") :]
+        )
+
+    @staticmethod
+    def _tidy() -> None:
+        """Remove the tool's output root when nothing is in it, so the project is as it was found.
+
+        The tool makes the root on *every* call, before it knows whether the output will need
+        keeping, and takes only its own folder away again: a command that printed a line leaves an
+        empty ``.zett-tool-output`` behind, which is the folder a reader sees in their project.
+
+        This is done here, on the event loop, and not with the move on a thread, on purpose. A
+        command about to run makes the root and then, on the very next line and with nothing
+        awaited between, makes its folder in it; two commands on the loop cannot interleave
+        there, and a removal from a thread could land between the two and fail a command that
+        did nothing wrong. A root with anything in it — a neighbour's running command — is not
+        empty, and the removal fails, which is the right answer.
+        """
+        try:
+            (Path.cwd().resolve() / OUTPUT_ROOT).rmdir()
+        except OSError:
+            pass
+
+    def _relocate(self, out: str, err: str, session_id: str) -> tuple[str, str] | None:
+        """Move the folder the two paths name, and return where its two files now are.
+
+        Only a folder the tool itself would have made is moved: a direct child of the tool's
+        output root, named like its own, holding exactly the two streams it names. Anything
+        else — a path a command printed, a folder that is not there — is left alone.
+
+        Returns:
+            The new paths of the standard output and error files, or ``None`` when nothing was
+            moved.
+        """
+        first, second = PurePosixPath(out), PurePosixPath(err)
+        if (
+            len(first.parts) != 3
+            or first.parts[0] != OUTPUT_ROOT
+            or not first.parts[1].startswith("shell-")
+            or first.parts[:2] != second.parts[:2]
+            or first.name != "stdout.txt"
+            or second.name != "stderr.txt"
+            or len(second.parts) != 3
+        ):
+            return None
+        source = Path.cwd().resolve() / OUTPUT_ROOT / first.parts[1]
+        try:
+            if not (source / "stdout.txt").is_file() or not (source / "stderr.txt").is_file():
+                return None
+            kept = self._store.session_dir(session_id) / KEPT_OUTPUT
+            kept.mkdir(parents=True, exist_ok=True)
+            target = kept / source.name
+            suffix = 1
+            while target.exists():
+                suffix += 1
+                target = kept / f"{source.name}-{suffix}"
+            shutil.move(str(source), str(target))
+        except (OSError, ValueError):
+            return None
+        return str(target / "stdout.txt"), str(target / "stderr.txt")

zettcode/tool_output/plugin.py

@@ -0,0 +1,25 @@
+"""The plugin that moves a shell command's kept output into the session's folder."""
+
+from __future__ import annotations
+
+from zettcode.engine.plugins.context import PluginContext
+from zettcode.engine.plugins.plugin import Plugin
+from zettcode.engine.plugins.services import PERSISTENCE
+from zettcode.engine.storage import SessionStore
+
+from .extension import ToolOutputExtension
+
+
+class ToolOutput(Plugin[PluginContext]):
+    """Moves a long tool result into the session's folder before it is stored or sent anywhere.
+
+    The extension acts on what the ``bash`` tool wrote, so it registers at the same priority as the coding bundle and
+    is handed over after it: a run keeps the order the extensions registered in wherever their priorities agree.
+    """
+
+    name = "tool-output"
+    description = "Keeps long tool output in the session folder"
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Register the extension over the session store."""
+        ctx.agent.register_extension(ToolOutputExtension(ctx.service(PERSISTENCE, SessionStore)))

zettcode_tool_output-0.4.1.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: zettcode-tool-output
+Version: 0.4.1
+Summary: The kept shell output of ZettCode, moved into the session's folder, as a part of the agent that lives apart from it
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: agent,tool-output,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.10
+Requires-Dist: zettcode-engine

zettcode_tool_output-0.4.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+zettcode/tool_output/__init__.py,sha256=s9HHlPVeYAF95hmF4ergSkIXmab2DDwYo1tZe5g32Rc,547
+zettcode/tool_output/extension.py,sha256=KMopW49QN7sOIfLWPTc0kAd7SIDBSwHsghEz1qRRieQ,7121
+zettcode/tool_output/plugin.py,sha256=vhhl1_6OHNe8wgN3RVvqq2NZ9jyXqN_lekAzbkPEgEQ,1062
+zettcode/tool_output/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zettcode_tool_output-0.4.1.dist-info/METADATA,sha256=YRgNijsbaBpIt8aGr6ADcXyl1ZCRSsFsYKcktRSommw,821
+zettcode_tool_output-0.4.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zettcode_tool_output-0.4.1.dist-info/entry_points.txt,sha256=YUY_F_LCmgSii2mIcDlom7yEY7wj8Uvxeh1crLcHH4Q,71
+zettcode_tool_output-0.4.1.dist-info/RECORD,,

zettcode_tool_output-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_tool_output-0.4.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[zettcode.plugin]
+tool-output = zettcode.tool_output.plugin:ToolOutput