zettcode-tool-output 0.4.1__tar.gz

zettcode_tool_output-0.4.1/.gitignore

@@ -0,0 +1,42 @@
+**/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.smoke/
+.coverage
+**/.pytest_cache/
+**/.ruff_cache/
+.zett-tool-output/
+.env
+.DS_Store
+
+# viztracer writes its trace here by default.
+/result.json
+
+# The docs site: dependencies, build output, and VitePress' cache.
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
+# The gateway's page is built from clients/gateway into the package when a distribution is made (`make gateway-ui`);
+# the build output is not kept in the repository. pyproject's `artifacts` puts it in the wheel all the same.
+packages/zettcode-gateway/src/zettcode/gateway/static/
+
+# The palette gallery is generated by `make palettes`: every widget painted in
+# every palette, written by docs/scripts/palette_gallery.py. Regenerate it
+# rather than committing a 2 MB copy that goes stale the moment a colour moves.
+docs/internal/palettes.html
+
+# The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
+packages/order.txt
+
+# The desktop and phone apps build the gateway's page into their own folders, and electron-builder writes its
+# installers under release/.
+clients/desktop/renderer/
+clients/desktop/release/

zettcode_tool_output-0.4.1/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "zettcode-tool-output"
+description = "The kept shell output of ZettCode, moved into the session's folder, as a part of the agent that lives apart from it"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "tool-output", "agent"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [
+  # The plugin base classes, the session store the extension moves the output into, and the name it is handed under.
+  "zettcode-engine",
+  # The extension, its hooks and the messages it rewrites.
+  "zett-agent>=0.2.10,<0.3",
+]
+
+# A part of the program, not a plugin: the `[tool.zettcode] plugin = true` marker is what the plugin release line looks for. It is
+# activated with the agent's other parts and nothing turns it off: without it a command's output would be left in the
+# reader's project.
+[project.entry-points."zettcode.plugin"]
+tool-output = "zettcode.tool_output.plugin:ToolOutput"
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# One version for the whole repository: the engine ships the file.
+path = "../zettcode-engine/src/zettcode/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

zettcode_tool_output-0.4.1/src/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-0.4.1/src/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-0.4.1/src/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)))