artifact-tool-v3 3.0.0__tar.gz

artifact_tool_v3-3.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

artifact_tool_v3-3.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: artifact_tool_v3
+Version: 3.0.0
+Summary: Host-side library for managing files generated in an agent sandbox.
+Author: artifact_tool_v3
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# artifact_tool_v3
+
+Host-side library for managing artifacts an agent writes into a sandbox workspace.
+
+Same core as `artifact_tool_v2`, plus glob filters, a JSON manifest, a size summary, and workspace cleanup.
+
+## Install
+
+```bash
+pip install artifact_tool_v3
+```
+
+## Workspace location
+
+Each sandbox lives at `{root}/{sandbox_id}/`.
+
+Root is resolved in this order:
+
+1. The `root=` argument to `ArtifactManager`
+2. The `ARTIFACT_TOOL_V3_ROOT` environment variable
+3. `~/.artifact_tool_v3`
+
+## Usage
+
+```python
+from artifact_tool_v3 import ArtifactManager
+
+mgr = ArtifactManager("run-123")
+workspace = mgr.ensure_workspace()
+
+artifacts = mgr.discover()
+pngs = mgr.list(glob="**/*.png")
+print(mgr.summary())
+mgr.write_manifest(workspace / "manifest.json")
+mgr.export("/tmp/out.zip", format="zip")
+mgr.cleanup()
+```

artifact_tool_v3-3.0.0/README.md

@@ -0,0 +1,37 @@
+# artifact_tool_v3
+
+Host-side library for managing artifacts an agent writes into a sandbox workspace.
+
+Same core as `artifact_tool_v2`, plus glob filters, a JSON manifest, a size summary, and workspace cleanup.
+
+## Install
+
+```bash
+pip install artifact_tool_v3
+```
+
+## Workspace location
+
+Each sandbox lives at `{root}/{sandbox_id}/`.
+
+Root is resolved in this order:
+
+1. The `root=` argument to `ArtifactManager`
+2. The `ARTIFACT_TOOL_V3_ROOT` environment variable
+3. `~/.artifact_tool_v3`
+
+## Usage
+
+```python
+from artifact_tool_v3 import ArtifactManager
+
+mgr = ArtifactManager("run-123")
+workspace = mgr.ensure_workspace()
+
+artifacts = mgr.discover()
+pngs = mgr.list(glob="**/*.png")
+print(mgr.summary())
+mgr.write_manifest(workspace / "manifest.json")
+mgr.export("/tmp/out.zip", format="zip")
+mgr.cleanup()
+```

artifact_tool_v3-3.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "artifact_tool_v3"
+version = "3.0.0"
+description = "Host-side library for managing files generated in an agent sandbox."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "artifact_tool_v3" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

artifact_tool_v3-3.0.0/src/artifact_tool_v3/__init__.py

@@ -0,0 +1,7 @@
+"""Host-side helpers for artifacts written into an agent sandbox."""
+
+from artifact_tool_v3.manager import ArtifactManager
+from artifact_tool_v3.models import Artifact
+
+__all__ = ["Artifact", "ArtifactManager"]
+__version__ = "3.0.0"

artifact_tool_v3-3.0.0/src/artifact_tool_v3/manager.py

@@ -0,0 +1,165 @@
+"""Scan, filter, and export files an agent wrote into a sandbox workspace."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import shutil
+import zipfile
+from datetime import datetime, timezone
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Literal
+
+from artifact_tool_v3.models import Artifact
+from artifact_tool_v3.paths import workspace_path
+
+ExportFormat = Literal["dir", "zip"]
+
+
+class ArtifactManager:
+    """Host handle for one sandbox workspace keyed by sandbox_id."""
+
+    def __init__(
+        self,
+        sandbox_id: str,
+        *,
+        root: str | os.PathLike[str] | None = None,
+    ) -> None:
+        self.sandbox_id = sandbox_id
+        self._workspace = workspace_path(sandbox_id, root)
+
+    @property
+    def workspace_path(self) -> Path:
+        """Absolute path the agent should write artifacts into."""
+        return self._workspace
+
+    def ensure_workspace(self) -> Path:
+        """Create the workspace directory if needed and return its path."""
+        self._workspace.mkdir(parents=True, exist_ok=True)
+        return self._workspace
+
+    def discover(self) -> list[Artifact]:
+        """Walk the workspace and return metadata for every file and directory.
+
+        Missing workspaces are treated as empty so the host can call discover
+        before the agent has created anything.
+        """
+        if not self._workspace.exists():
+            return []
+
+        artifacts: list[Artifact] = []
+        for path in sorted(self._workspace.rglob("*")):
+            artifacts.append(_artifact_from_path(path, self._workspace))
+        return artifacts
+
+    def list(
+        self,
+        *,
+        name: str | None = None,
+        suffix: str | None = None,
+        type: str | None = None,
+        glob: str | None = None,
+    ) -> list[Artifact]:
+        """Discover artifacts and keep those matching the given filters.
+
+        `glob` is matched against the posix relative path (for example `**/*.png`).
+        """
+        results = self.discover()
+        if name is not None:
+            results = [item for item in results if item.name == name]
+        if suffix is not None:
+            expected = suffix if suffix.startswith(".") else f".{suffix}"
+            results = [
+                item
+                for item in results
+                if Path(item.name).suffix.lower() == expected.lower()
+            ]
+        if type is not None:
+            results = [item for item in results if item.type == type]
+        if glob is not None:
+            results = [item for item in results if fnmatch(item.relative_path, glob)]
+        return results
+
+    def summary(self) -> dict[str, int]:
+        """Return file/dir counts and total file bytes for this workspace."""
+        artifacts = self.discover()
+        files = [item for item in artifacts if not item.is_dir]
+        dirs = [item for item in artifacts if item.is_dir]
+        return {
+            "files": len(files),
+            "directories": len(dirs),
+            "total_bytes": sum(item.size for item in files),
+        }
+
+    def write_manifest(self, destination: str | os.PathLike[str] | None = None) -> Path:
+        """Write a JSON listing of every discovered artifact and return its path."""
+        dest = Path(destination) if destination is not None else self.ensure_workspace() / "manifest.json"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "sandbox_id": self.sandbox_id,
+            "workspace": str(self._workspace),
+            "artifacts": [item.to_dict() for item in self.discover()],
+        }
+        dest.write_text(json.dumps(payload, indent=2) + "\n")
+        return dest.resolve()
+
+    def cleanup(self) -> None:
+        """Delete the sandbox workspace directory if it exists."""
+        if self._workspace.exists():
+            shutil.rmtree(self._workspace)
+
+    def export(
+        self,
+        destination: str | os.PathLike[str],
+        *,
+        format: ExportFormat = "dir",
+    ) -> Path:
+        """Copy the workspace to a directory or zip archive of relative paths."""
+        dest = Path(destination)
+        if format == "dir":
+            return self._export_dir(dest)
+        if format == "zip":
+            return self._export_zip(dest)
+        raise ValueError(f"unsupported export format: {format!r}")
+
+    def _export_dir(self, destination: Path) -> Path:
+        """Copy the workspace tree into destination, creating parents as needed."""
+        if not self._workspace.exists():
+            destination.mkdir(parents=True, exist_ok=True)
+            return destination.resolve()
+
+        if destination.exists():
+            shutil.copytree(self._workspace, destination, dirs_exist_ok=True)
+        else:
+            shutil.copytree(self._workspace, destination)
+        return destination.resolve()
+
+    def _export_zip(self, destination: Path) -> Path:
+        """Write a zip whose member names are paths relative to the workspace."""
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(destination, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            if self._workspace.exists():
+                for path in sorted(self._workspace.rglob("*")):
+                    archive.write(path, arcname=path.relative_to(self._workspace).as_posix())
+        return destination.resolve()
+
+
+def _artifact_from_path(path: Path, workspace: Path) -> Artifact:
+    """Build Artifact metadata from a filesystem stat of path."""
+    stat = path.stat()
+    is_dir = path.is_dir()
+    mime_type, _ = mimetypes.guess_type(path.name)
+    if is_dir:
+        mime_type = "inode/directory"
+
+    return Artifact(
+        name=path.name,
+        relative_path=path.relative_to(workspace).as_posix(),
+        path=path.resolve(),
+        type=mime_type,
+        size=0 if is_dir else stat.st_size,
+        created_at=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc),
+        is_dir=is_dir,
+    )

artifact_tool_v3-3.0.0/src/artifact_tool_v3/models.py

@@ -0,0 +1,32 @@
+"""In-memory description of one file or directory in a sandbox workspace."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """Metadata for one path discovered under a sandbox workspace."""
+
+    name: str
+    relative_path: str
+    path: Path
+    type: str | None
+    size: int
+    created_at: datetime
+    is_dir: bool
+
+    def to_dict(self) -> dict[str, object]:
+        """JSON-friendly record used by manifests and summaries."""
+        return {
+            "name": self.name,
+            "relative_path": self.relative_path,
+            "path": str(self.path),
+            "type": self.type,
+            "size": self.size,
+            "created_at": self.created_at.isoformat(),
+            "is_dir": self.is_dir,
+        }

artifact_tool_v3-3.0.0/src/artifact_tool_v3/paths.py

@@ -0,0 +1,50 @@
+"""Resolve the on-disk root and per-sandbox workspace path."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Used when the caller does not pass root= and the env var is unset.
+DEFAULT_ROOT_DIRNAME = ".artifact_tool_v3"
+ROOT_ENV_VAR = "ARTIFACT_TOOL_V3_ROOT"
+
+
+class InvalidSandboxIdError(ValueError):
+    """Raised when sandbox_id would escape or collide with the store root."""
+
+
+def resolve_root(root: str | os.PathLike[str] | None = None) -> Path:
+    """Pick the store root: explicit path, env var, then ~/.artifact_tool_v3."""
+    if root is not None:
+        return Path(root).expanduser().resolve()
+
+    env_root = os.environ.get(ROOT_ENV_VAR)
+    if env_root:
+        return Path(env_root).expanduser().resolve()
+
+    return (Path.home() / DEFAULT_ROOT_DIRNAME).resolve()
+
+
+def validate_sandbox_id(sandbox_id: str) -> str:
+    """Reject ids that contain path separators or parent-directory references."""
+    if not sandbox_id or not sandbox_id.strip():
+        raise InvalidSandboxIdError("sandbox_id must be a non-empty string")
+
+    if sandbox_id != sandbox_id.strip():
+        raise InvalidSandboxIdError("sandbox_id must not have leading or trailing whitespace")
+
+    # Block both POSIX and Windows separators so an id cannot walk the tree.
+    if "/" in sandbox_id or "\\" in sandbox_id or os.sep in sandbox_id:
+        raise InvalidSandboxIdError("sandbox_id must not contain path separators")
+
+    if sandbox_id in {".", ".."} or ".." in sandbox_id:
+        raise InvalidSandboxIdError("sandbox_id must not contain '..' or be '.'")
+
+    return sandbox_id
+
+
+def workspace_path(sandbox_id: str, root: str | os.PathLike[str] | None = None) -> Path:
+    """Return `{root}/{sandbox_id}` after validating the id."""
+    safe_id = validate_sandbox_id(sandbox_id)
+    return resolve_root(root) / safe_id

artifact_tool_v3-3.0.0/tests/test_manager.py

@@ -0,0 +1,157 @@
+"""Tests for workspace creation, discovery, filters, and export."""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from artifact_tool_v3 import ArtifactManager
+from artifact_tool_v3.paths import InvalidSandboxIdError
+
+
+def _write_file(path: Path, content: str = "hello") -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+def test_ensure_workspace_creates_sandbox_directory(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-123", root=tmp_path)
+
+    workspace = mgr.ensure_workspace()
+
+    assert workspace == tmp_path / "run-123"
+    assert workspace.is_dir()
+    assert mgr.workspace_path == workspace
+
+
+@pytest.mark.parametrize("sandbox_id", ["", "  ", "a/b", r"a\b", "..", "foo..bar", "."])
+def test_invalid_sandbox_ids_are_rejected(tmp_path: Path, sandbox_id: str) -> None:
+    with pytest.raises(InvalidSandboxIdError):
+        ArtifactManager(sandbox_id, root=tmp_path)
+
+
+def test_discover_returns_empty_for_missing_or_empty_workspace(tmp_path: Path) -> None:
+    mgr = ArtifactManager("empty-run", root=tmp_path)
+
+    assert mgr.discover() == []
+
+    mgr.ensure_workspace()
+    assert mgr.discover() == []
+
+
+def test_discover_collects_file_and_directory_metadata(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-meta", root=tmp_path)
+    workspace = mgr.ensure_workspace()
+    plots = workspace / "plots"
+    report = workspace / "report.json"
+    image = plots / "chart.png"
+    _write_file(report, '{"ok": true}')
+    _write_file(image, "png-bytes")
+
+    artifacts = {item.relative_path: item for item in mgr.discover()}
+
+    assert set(artifacts) == {"plots", "plots/chart.png", "report.json"}
+
+    json_artifact = artifacts["report.json"]
+    assert json_artifact.name == "report.json"
+    assert json_artifact.path == report.resolve()
+    assert json_artifact.type == "application/json"
+    assert json_artifact.size == report.stat().st_size
+    assert json_artifact.is_dir is False
+    assert json_artifact.created_at.tzinfo is not None
+
+    dir_artifact = artifacts["plots"]
+    assert dir_artifact.is_dir is True
+    assert dir_artifact.type == "inode/directory"
+    assert dir_artifact.size == 0
+
+
+def test_list_filters_by_name_suffix_type_and_glob(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-filter", root=tmp_path)
+    workspace = mgr.ensure_workspace()
+    _write_file(workspace / "notes.txt", "txt")
+    _write_file(workspace / "plots" / "chart.PNG", "img")
+    _write_file(workspace / "report.json", "{}")
+
+    by_name = mgr.list(name="notes.txt")
+    assert [item.relative_path for item in by_name] == ["notes.txt"]
+
+    by_suffix = mgr.list(suffix=".png")
+    assert [item.relative_path for item in by_suffix] == ["plots/chart.PNG"]
+
+    by_type = mgr.list(type="application/json")
+    assert [item.relative_path for item in by_type] == ["report.json"]
+
+    by_glob = mgr.list(glob="plots/*")
+    assert [item.relative_path for item in by_glob] == ["plots/chart.PNG"]
+
+
+def test_summary_counts_files_and_bytes(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-summary", root=tmp_path)
+    workspace = mgr.ensure_workspace()
+    _write_file(workspace / "a.txt", "ab")
+    _write_file(workspace / "nested" / "b.txt", "cd")
+
+    assert mgr.summary() == {"files": 2, "directories": 1, "total_bytes": 4}
+
+
+def test_write_manifest_and_cleanup(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-manifest", root=tmp_path)
+    workspace = mgr.ensure_workspace()
+    _write_file(workspace / "out.txt", "payload")
+
+    dest = tmp_path / "manifest.json"
+    result = mgr.write_manifest(dest)
+    payload = json.loads(result.read_text())
+
+    assert payload["sandbox_id"] == "run-manifest"
+    assert any(item["name"] == "out.txt" for item in payload["artifacts"])
+
+    mgr.cleanup()
+    assert not workspace.exists()
+    assert mgr.discover() == []
+
+
+def test_export_dir_copies_workspace_tree(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-export-dir", root=tmp_path)
+    workspace = mgr.ensure_workspace()
+    _write_file(workspace / "nested" / "out.txt", "payload")
+
+    dest = tmp_path / "bundle"
+    result = mgr.export(dest, format="dir")
+
+    assert result == dest.resolve()
+    assert (dest / "nested" / "out.txt").read_text() == "payload"
+
+
+def test_export_zip_uses_relative_member_names(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-export-zip", root=tmp_path)
+    workspace = mgr.ensure_workspace()
+    _write_file(workspace / "nested" / "out.txt", "payload")
+
+    dest = tmp_path / "bundle.zip"
+    result = mgr.export(dest, format="zip")
+
+    assert result == dest.resolve()
+    with zipfile.ZipFile(dest) as archive:
+        names = set(archive.namelist())
+        assert "nested/out.txt" in names
+        assert archive.read("nested/out.txt") == b"payload"
+
+
+def test_export_empty_sandbox_creates_empty_dir_and_zip(tmp_path: Path) -> None:
+    mgr = ArtifactManager("run-export-empty", root=tmp_path)
+
+    dir_dest = tmp_path / "empty-bundle"
+    zip_dest = tmp_path / "empty.zip"
+
+    mgr.export(dir_dest, format="dir")
+    mgr.export(zip_dest, format="zip")
+
+    assert dir_dest.is_dir()
+    assert list(dir_dest.iterdir()) == []
+    with zipfile.ZipFile(zip_dest) as archive:
+        assert archive.namelist() == []

artifact_tool_v3-3.0.0/tests/test_paths.py

@@ -0,0 +1,27 @@
+"""Tests for store-root resolution and sandbox_id rules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from artifact_tool_v3.paths import ROOT_ENV_VAR, resolve_root, workspace_path
+
+
+def test_resolve_root_prefers_argument_over_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(ROOT_ENV_VAR, str(tmp_path / "from-env"))
+    explicit = tmp_path / "explicit"
+
+    assert resolve_root(explicit) == explicit.resolve()
+
+
+def test_resolve_root_uses_env_when_argument_missing(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    env_root = tmp_path / "from-env"
+    monkeypatch.setenv(ROOT_ENV_VAR, str(env_root))
+
+    assert resolve_root() == env_root.resolve()
+
+
+def test_workspace_path_nests_under_root(tmp_path: Path) -> None:
+    assert workspace_path("run-abc", root=tmp_path) == (tmp_path / "run-abc").resolve()