ags-cli 0.1.0__py3-none-any.whl

harness/services/files.py

@@ -0,0 +1,287 @@
+"""Project-scoped filesystem access for the GUI file explorer.
+
+Every path is resolved (dereferencing symlinks) and asserted to live *inside* the
+workspace's active ``project_dir`` before any read **or write** — the local server has
+no auth in dev and may be bound to ``0.0.0.0``, so ``_safe_join`` is the only thing
+standing between the LAN and the whole filesystem. That guard matters even more for the
+mutating helpers below (write / create / rename / delete): every one of them routes its
+path(s) through ``_safe_join`` first. Deletes are *soft* — entries move into a
+``.ags-trash/`` folder at the project root rather than being unlinked — so an accidental
+call over an unauthenticated bind is recoverable. Sync helpers so they stay off the
+async hot path.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+# Files larger than this are not returned as text (the GUI shows a placeholder instead).
+MAX_FILE_BYTES = 1_000_000
+
+# Directory (relative to the project root) that soft-deleted entries are moved into.
+TRASH_DIRNAME = ".ags-trash"
+
+# Bounds for the search / quick-open walks so a huge tree can't hang the event loop.
+_WALK_MAX_FILES = 20_000
+_SEARCH_MAX_MATCHES = 500
+_FIND_MAX_MATCHES = 200
+# Directory names skipped when walking for search / quick-open.
+_SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", TRASH_DIRNAME}
+
+
+def _safe_join(project_dir: str, subpath: str) -> Path:
+    """Resolve ``subpath`` relative to ``project_dir`` and assert it stays within the
+    resolved root. Raises ``ValueError`` on traversal / symlink escape (the same
+    ``resolve() + relative_to`` check as ``PermissionContext.path_allowed``)."""
+    root = Path(project_dir).resolve()
+    target = (root / (subpath or "")).resolve()
+    try:
+        target.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"path outside project folder: {subpath!r}") from exc
+    return target
+
+
+def list_dir(project_dir: str, subpath: str = "") -> dict:
+    """List immediate entries of ``project_dir/subpath`` — dirs first, then files, each
+    sorted case-insensitively. Dotfiles are hidden (matches ``browse_dirs``). Returns
+    ``{ root, subpath, parent, entries: [{name, type, size}] }``."""
+    target = _safe_join(project_dir, subpath)
+    if not target.is_dir():
+        raise ValueError(f"not a directory: {subpath!r}")
+
+    dirs: list[dict] = []
+    files: list[dict] = []
+    try:
+        for entry in os.scandir(target):
+            if entry.name.startswith("."):
+                continue
+            if entry.is_dir():
+                dirs.append({"name": entry.name, "type": "dir", "size": 0})
+            elif entry.is_file():
+                try:
+                    size = entry.stat().st_size
+                except OSError:
+                    size = 0
+                files.append({"name": entry.name, "type": "file", "size": size})
+    except OSError:
+        pass
+    dirs.sort(key=lambda e: e["name"].lower())
+    files.sort(key=lambda e: e["name"].lower())
+
+    norm = "" if subpath in ("", ".") else os.path.normpath(subpath).strip("/")
+    parent = os.path.dirname(norm) if norm else None
+    return {
+        "root": str(Path(project_dir).resolve()),
+        "subpath": norm,
+        "parent": parent,
+        "entries": dirs + files,
+    }
+
+
+def read_file(project_dir: str, subpath: str, max_bytes: int = MAX_FILE_BYTES) -> dict:
+    """Read ``project_dir/subpath`` as UTF-8 text. Returns
+    ``{ name, subpath, size, truncated, binary, text }``. Over the size cap →
+    ``truncated`` with no text; non-UTF-8 bytes → ``binary`` with no text."""
+    target = _safe_join(project_dir, subpath)
+    if not target.is_file():
+        raise ValueError(f"not a file: {subpath!r}")
+
+    size = target.stat().st_size
+    base = {"name": target.name, "subpath": os.path.normpath(subpath).strip("/"), "size": size}
+    if size > max_bytes:
+        return {**base, "truncated": True, "binary": False, "text": None}
+    raw = target.read_bytes()
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return {**base, "truncated": False, "binary": True, "text": None}
+    return {**base, "truncated": False, "binary": False, "text": text}
+
+
+def file_path(project_dir: str, subpath: str) -> Path:
+    """Resolve ``subpath`` to an existing file path inside the project, for raw byte
+    serving (images, downloads). Raises ``ValueError`` on traversal or non-file."""
+    target = _safe_join(project_dir, subpath)
+    if not target.is_file():
+        raise ValueError(f"not a file: {subpath!r}")
+    return target
+
+
+def write_file(project_dir: str, subpath: str, text: str, max_bytes: int = MAX_FILE_BYTES) -> dict:
+    """Write UTF-8 ``text`` to ``project_dir/subpath``, creating the file if needed.
+    Refuses paths that resolve to a directory or exceed ``max_bytes``. Parent
+    directories must already exist. Returns the same shape as :func:`read_file`."""
+    encoded = text.encode("utf-8")
+    if len(encoded) > max_bytes:
+        raise ValueError(f"file too large: {len(encoded)} bytes > {max_bytes} cap")
+    target = _safe_join(project_dir, subpath)
+    if target.is_dir():
+        raise ValueError(f"is a directory: {subpath!r}")
+    if not target.parent.is_dir():
+        raise ValueError(f"parent folder does not exist: {subpath!r}")
+    target.write_bytes(encoded)
+    return read_file(project_dir, subpath, max_bytes=max_bytes)
+
+
+def create_entry(project_dir: str, subpath: str, kind: str) -> dict:
+    """Create a new empty file (``kind="file"``) or directory (``kind="dir"``) at
+    ``subpath``. Creates missing parent directories. Raises ``ValueError`` if the
+    entry already exists or ``kind`` is invalid. Returns ``{subpath, type}``."""
+    if kind not in ("file", "dir"):
+        raise ValueError(f"invalid kind: {kind!r} (expected 'file' or 'dir')")
+    target = _safe_join(project_dir, subpath)
+    if target.exists():
+        raise ValueError(f"already exists: {subpath!r}")
+    if kind == "dir":
+        target.mkdir(parents=True)
+    else:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.touch()
+    norm = os.path.normpath(subpath).strip("/")
+    return {"subpath": norm, "type": kind}
+
+
+def rename_entry(project_dir: str, src: str, dst: str) -> dict:
+    """Rename/move ``src`` to ``dst`` (both project-scoped). Raises ``ValueError`` when
+    ``src`` is missing, ``dst`` already exists, or ``dst``'s parent is missing.
+    Returns ``{src, dst}`` with normalized paths."""
+    src_path = _safe_join(project_dir, src)
+    dst_path = _safe_join(project_dir, dst)
+    if not src_path.exists():
+        raise ValueError(f"not found: {src!r}")
+    if dst_path.exists():
+        raise ValueError(f"already exists: {dst!r}")
+    if not dst_path.parent.is_dir():
+        raise ValueError(f"destination folder does not exist: {dst!r}")
+    src_path.rename(dst_path)
+    return {"src": os.path.normpath(src).strip("/"), "dst": os.path.normpath(dst).strip("/")}
+
+
+def delete_entry(project_dir: str, subpath: str) -> dict:
+    """Soft-delete ``subpath`` by moving it into ``<project>/.ags-trash/``. A name
+    collision in the trash is resolved with a numeric suffix. Raises ``ValueError``
+    if the entry is missing or is the trash folder itself. Returns
+    ``{subpath, trashed_to}`` (trash path relative to the project root)."""
+    target = _safe_join(project_dir, subpath)
+    if not target.exists():
+        raise ValueError(f"not found: {subpath!r}")
+    trash = _safe_join(project_dir, TRASH_DIRNAME)
+    if target == trash:
+        raise ValueError("cannot delete the trash folder")
+    trash.mkdir(parents=True, exist_ok=True)
+    dest = trash / target.name
+    suffix = 1
+    while dest.exists():
+        dest = trash / f"{target.name}.{suffix}"
+        suffix += 1
+    shutil.move(str(target), str(dest))
+    return {
+        "subpath": os.path.normpath(subpath).strip("/"),
+        "trashed_to": f"{TRASH_DIRNAME}/{dest.name}",
+    }
+
+
+def _iter_files(root: Path):
+    """Yield ``(abs_path, rel_posix)`` for files under ``root``, skipping hidden and
+    heavy directories, bounded by ``_WALK_MAX_FILES``."""
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d not in _SKIP_DIRS]
+        for name in filenames:
+            if name.startswith("."):
+                continue
+            abs_path = Path(dirpath) / name
+            rel = abs_path.relative_to(root).as_posix()
+            yield abs_path, rel
+            count += 1
+            if count >= _WALK_MAX_FILES:
+                return
+
+
+def find_files(project_dir: str, query: str, limit: int = _FIND_MAX_MATCHES) -> dict:
+    """Quick-open: return files whose relative path contains every whitespace-separated
+    token of ``query`` (case-insensitive). Empty query returns no matches. Result:
+    ``{query, truncated, matches: [{subpath, name}]}``."""
+    root = Path(project_dir).resolve()
+    tokens = [t.lower() for t in query.split() if t]
+    matches: list[dict] = []
+    truncated = False
+    if tokens:
+        for _abs, rel in _iter_files(root):
+            low = rel.lower()
+            if all(t in low for t in tokens):
+                matches.append({"subpath": rel, "name": rel.rsplit("/", 1)[-1]})
+                if len(matches) >= limit:
+                    truncated = True
+                    break
+    matches.sort(key=lambda m: (len(m["subpath"]), m["subpath"].lower()))
+    return {"query": query, "truncated": truncated, "matches": matches}
+
+
+def search_content(project_dir: str, query: str, limit: int = _SEARCH_MAX_MATCHES) -> dict:
+    """Full-text search across project files. Prefers ``ripgrep`` (``rg``) when on PATH,
+    else a bounded Python walk. Case-insensitive, fixed-string match. Result:
+    ``{query, truncated, matches: [{subpath, line, text}]}``."""
+    root = Path(project_dir).resolve()
+    if not query:
+        return {"query": query, "truncated": False, "matches": []}
+    rg = shutil.which("rg")
+    if rg:
+        return _search_ripgrep(rg, root, query, limit)
+    return _search_python(root, query, limit)
+
+
+def _search_ripgrep(rg: str, root: Path, query: str, limit: int) -> dict:
+    """ripgrep fixed-string, case-insensitive search. ``query`` is passed as a single
+    argv element (never a shell string), so it can't inject flags/commands."""
+    args = [
+        rg, "--fixed-strings", "--ignore-case", "--line-number", "--no-heading",
+        "--with-filename", "--max-count", "50", "--color", "never",
+        "-g", f"!{TRASH_DIRNAME}", "--", query, ".",
+    ]
+    try:
+        proc = subprocess.run(args, cwd=root, capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired):
+        return _search_python(root, query, limit)
+    matches: list[dict] = []
+    truncated = False
+    for raw in proc.stdout.splitlines():
+        # Format: path:line:text  (path may itself contain ':' — split at most twice).
+        parts = raw.split(":", 2)
+        if len(parts) < 3:
+            continue
+        path, lineno, text = parts
+        try:
+            line = int(lineno)
+        except ValueError:
+            continue
+        matches.append({"subpath": path.lstrip("./"), "line": line, "text": text[:400]})
+        if len(matches) >= limit:
+            truncated = True
+            break
+    return {"query": query, "truncated": truncated, "matches": matches}
+
+
+def _search_python(root: Path, query: str, limit: int) -> dict:
+    """Fallback content search: walk files and scan UTF-8 lines for ``query`` (ci)."""
+    needle = query.lower()
+    matches: list[dict] = []
+    truncated = False
+    for abs_path, rel in _iter_files(root):
+        try:
+            if abs_path.stat().st_size > MAX_FILE_BYTES:
+                continue
+            raw = abs_path.read_bytes()
+            text = raw.decode("utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for i, line in enumerate(text.splitlines(), start=1):
+            if needle in line.lower():
+                matches.append({"subpath": rel, "line": i, "text": line[:400]})
+                if len(matches) >= limit:
+                    return {"query": query, "truncated": True, "matches": matches}
+    return {"query": query, "truncated": truncated, "matches": matches}

harness/services/mcp_servers.py

@@ -0,0 +1,179 @@
+"""GUI-managed MCP servers — create/update/delete that take effect immediately.
+
+Mirrors the provider-management service: each GUI-added server is persisted durably as
+a ``~/.ags/mcp.d/<name>.yaml`` overlay (so a re-seed/restart keeps it) AND upserted into
+the ``mcp_server_configs`` table. The engine reads MCP servers from the DB live on every
+run, so a change here is in effect on the next run with **no restart**.
+
+Servers declared in ``config.yaml`` are read-only from the GUI (edit the file instead);
+only overlay-managed servers can be updated or deleted. An optional bearer token is held
+as a ``0600`` file secret (``secret_ref``), never in the DB.
+"""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.enums import McpTransport
+from harness.models.mcp_server_config import McpServerConfig
+from harness.observability.audit import write_audit
+from harness.security.secrets import delete_secret_file, write_secret_file
+from harness.settings import MCP_DIR, get_settings
+
+_NAME_RE = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}")
+
+
+def _server_file(name: str):
+    return MCP_DIR / f"{name}.yaml"
+
+
+def managed_mcp_names() -> set[str]:
+    """Names of GUI-added (overlay) MCP servers — the editable/deletable ones."""
+    if not MCP_DIR.is_dir():
+        return set()
+    return {f.stem for f in MCP_DIR.glob("*.yaml")}
+
+
+async def list_mcp_servers(db: AsyncSession) -> list[McpServerConfig]:
+    return list(
+        (await db.execute(select(McpServerConfig).order_by(McpServerConfig.name))).scalars()
+    )
+
+
+async def _named(db: AsyncSession, name: str) -> McpServerConfig | None:
+    return (
+        await db.execute(select(McpServerConfig).where(McpServerConfig.name == name))
+    ).scalar_one_or_none()
+
+
+def _entry(
+    *, name: str, transport: str, command, args, env, url, headers,
+    secret_ref, tool_allowlist, bind, read_only, enabled,
+) -> dict:
+    """The overlay-file shape (also used to set DB columns)."""
+    return {
+        "name": name, "transport": transport, "command": command, "args": args or [],
+        "env": env or {}, "url": url, "headers": headers or {}, "secret_ref": secret_ref,
+        "tool_allowlist": tool_allowlist or [], "bind": bind or {},
+        "read_only": bool(read_only), "enabled": bool(enabled),
+    }
+
+
+def _apply(row: McpServerConfig, e: dict) -> None:
+    row.transport = McpTransport(e["transport"])
+    row.command = e.get("command")
+    row.args = e.get("args") or []
+    row.env = e.get("env") or {}
+    row.url = e.get("url")
+    row.headers = e.get("headers") or {}
+    row.secret_ref = e.get("secret_ref")
+    row.tool_allowlist = e.get("tool_allowlist") or []
+    row.bind = e.get("bind") or {}
+    row.read_only = bool(e.get("read_only"))
+    row.enabled = bool(e.get("enabled", True))
+
+
+def _write_overlay(name: str, e: dict) -> None:
+    MCP_DIR.mkdir(parents=True, exist_ok=True)
+    _server_file(name).write_text(yaml.safe_dump(e, sort_keys=False))
+    get_settings().reset_config_cache()
+
+
+async def create_mcp_server(
+    db: AsyncSession, *, name: str, transport: str = "stdio",
+    command: str | None = None, args: list | None = None, env: dict | None = None,
+    url: str | None = None, headers: dict | None = None, token: str | None = None,
+    tool_allowlist: list | None = None, read_only: bool = False, enabled: bool = True,
+    actor: str = "gui",
+) -> dict:
+    name = (name or "").strip().lower()
+    if not _NAME_RE.fullmatch(name):
+        raise ValueError("name must be lowercase letters/digits/-/_ (e.g. 'github')")
+    if transport not in ("stdio", "http"):
+        raise ValueError("transport must be 'stdio' or 'http'")
+    if transport == "stdio" and not (command or "").strip():
+        raise ValueError("stdio transport requires a command")
+    if transport == "http" and not (url or "").strip():
+        raise ValueError("http transport requires a url")
+    if await _named(db, name):
+        raise ValueError(f"MCP server '{name}' already exists")
+
+    secret_ref = (
+        write_secret_file(f"mcp-{name}", token.strip()) if token and token.strip() else None
+    )
+    e = _entry(
+        name=name, transport=transport, command=command, args=args, env=env, url=url,
+        headers=headers, secret_ref=secret_ref, tool_allowlist=tool_allowlist, bind={},
+        read_only=read_only, enabled=enabled,
+    )
+    _write_overlay(name, e)
+    row = McpServerConfig(name=name)
+    _apply(row, e)
+    db.add(row)
+    await db.flush()
+    await write_audit(
+        db, actor=actor, action="create_mcp_server", target_type="mcp_server", target_id=name,
+        before=None, after={"transport": transport, "has_token": bool(secret_ref)},
+    )
+    await db.commit()  # durable + live before we respond
+    return {"name": name, "transport": transport, "enabled": enabled}
+
+
+async def update_mcp_server(
+    db: AsyncSession, name: str, *, fields: dict, actor: str = "gui"
+) -> dict:
+    """Update an overlay-managed server. ``fields`` may include transport/command/args/
+    env/url/headers/token/tool_allowlist/read_only/enabled (only the keys present)."""
+    if not _server_file(name).exists():
+        raise ValueError(f"'{name}' is not a GUI-managed MCP server (edit config.yaml instead)")
+    row = await _named(db, name)
+    if row is None:
+        raise ValueError(f"MCP server '{name}' not found")
+    current = yaml.safe_load(_server_file(name).read_text()) or {}
+
+    # Token: a non-empty value rotates the file secret; an explicit empty string clears it.
+    if "token" in fields:
+        tok = (fields.pop("token") or "").strip()
+        if tok:
+            current["secret_ref"] = write_secret_file(f"mcp-{name}", tok)
+        else:
+            delete_secret_file(f"mcp-{name}")
+            current["secret_ref"] = None
+    current.update({k: v for k, v in fields.items() if k != "token"})
+    e = _entry(
+        name=name, transport=current.get("transport", "stdio"), command=current.get("command"),
+        args=current.get("args"), env=current.get("env"), url=current.get("url"),
+        headers=current.get("headers"), secret_ref=current.get("secret_ref"),
+        tool_allowlist=current.get("tool_allowlist"), bind=current.get("bind"),
+        read_only=current.get("read_only", False), enabled=current.get("enabled", True),
+    )
+    _write_overlay(name, e)
+    _apply(row, e)
+    await db.flush()
+    await write_audit(
+        db, actor=actor, action="update_mcp_server", target_type="mcp_server", target_id=name,
+        before=None, after={"enabled": e["enabled"], "transport": e["transport"]},
+    )
+    await db.commit()
+    return {"name": name, "enabled": e["enabled"]}
+
+
+async def delete_mcp_server(db: AsyncSession, name: str, *, actor: str = "gui") -> dict:
+    if not _server_file(name).exists():
+        raise ValueError(f"'{name}' is not a GUI-managed MCP server (edit config.yaml instead)")
+    _server_file(name).unlink()
+    delete_secret_file(f"mcp-{name}")
+    get_settings().reset_config_cache()
+    if (row := await _named(db, name)) is not None:
+        await db.delete(row)
+    await db.flush()
+    await write_audit(
+        db, actor=actor, action="delete_mcp_server", target_type="mcp_server", target_id=name,
+        before={"name": name}, after=None,
+    )
+    await db.commit()
+    return {"deleted": name}

harness/services/project_git.py

@@ -0,0 +1,101 @@
+"""Git status + per-file diff for the GUI Files panel, scoped to a workspace's active
+``project_dir``.
+
+Thin wrapper over the git subprocess helpers already used elsewhere: it reuses
+``worktrees._git`` (a timed, checked ``git`` runner) and ``worktrees.is_git_repo``, and
+mirrors the capped-diff pattern in ``runs_diff._git_diff``. All work runs sync (called
+via ``asyncio.to_thread`` from the API layer). Not-a-git-repo is a soft, empty result —
+the panel simply shows no badges — rather than an error.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from harness.services.worktrees import is_git_repo
+
+# Cap diff output so a huge change can't blow up the response (matches runs_diff).
+_MAX_DIFF_BYTES = 1_000_000
+
+
+# Map porcelain-v1 XY status codes to a single-letter class the UI renders as a badge.
+def _classify(xy: str) -> str:
+    """Collapse a 2-char porcelain status (e.g. ' M', 'A ', '??', 'R ') to one of
+    ``modified`` | ``added`` | ``deleted`` | ``renamed`` | ``untracked``."""
+    if xy == "??":
+        return "untracked"
+    codes = xy.strip()
+    if "R" in codes:
+        return "renamed"
+    if "D" in codes:
+        return "deleted"
+    if "A" in codes:
+        return "added"
+    return "modified"
+
+
+def git_status(project_dir: str) -> dict:
+    """Return ``{is_repo, files: {subpath: status}}`` for the working tree.
+
+    ``status`` is one of modified/added/deleted/renamed/untracked. Paths are
+    project-relative POSIX (as git reports them). Non-git dirs return
+    ``{is_repo: False, files: {}}`` rather than raising."""
+    if not is_git_repo(project_dir):
+        return {"is_repo": False, "files": {}}
+    try:
+        # Run directly (not via the shared ``_git`` helper): that helper strips stdout,
+        # which would eat the leading status column of the first porcelain line and
+        # corrupt the fixed-width XY parsing below.
+        proc = subprocess.run(
+            ["git", "status", "--porcelain"], cwd=project_dir,
+            capture_output=True, text=True, timeout=60,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return {"is_repo": True, "files": {}}
+    if proc.returncode != 0:
+        return {"is_repo": True, "files": {}}
+    files: dict[str, str] = {}
+    for line in proc.stdout.splitlines():
+        if len(line) < 3:
+            continue
+        xy = line[:2]
+        # porcelain v1: path after the XY+space; "old -> new" on renames.
+        name = line[3:].split(" -> ")[-1].strip().strip('"')
+        if name:
+            files[name] = _classify(xy)
+    return {"is_repo": True, "files": files}
+
+
+def file_diff(project_dir: str, subpath: str) -> dict:
+    """Return the working-tree diff for a single file vs HEAD (staged + unstaged).
+
+    Result: ``{subpath, diff, truncated, is_repo}``. For an untracked file (no HEAD
+    blob) falls back to ``git diff --no-index /dev/null <file>`` so new files still
+    show content. Non-git dirs return an empty diff with ``is_repo: False``."""
+    if not is_git_repo(project_dir):
+        return {"subpath": subpath, "diff": "", "truncated": False, "is_repo": False}
+    diff = _run_diff(project_dir, ["git", "diff", "HEAD", "--", subpath])
+    if not diff:
+        # Untracked file: HEAD has no blob, so `git diff HEAD` is empty. Compare to
+        # an empty tree to surface the full new-file content.
+        diff = _run_diff(
+            project_dir, ["git", "diff", "--no-index", "--", "/dev/null", subpath]
+        )
+    truncated = False
+    if len(diff.encode("utf-8", "replace")) > _MAX_DIFF_BYTES:
+        diff = diff.encode("utf-8", "replace")[:_MAX_DIFF_BYTES].decode("utf-8", "ignore")
+        truncated = True
+    return {"subpath": subpath, "diff": diff, "truncated": truncated, "is_repo": True}
+
+
+def _run_diff(project_dir: str, argv: list[str]) -> str:
+    """Run a ``git diff`` variant, returning stdout. ``git diff`` exits non-zero (1)
+    simply when differences exist, and ``--no-index`` always exits 1 on a diff, so we
+    return stdout regardless of return code (unlike the checked ``_git`` helper)."""
+    try:
+        result = subprocess.run(
+            argv, cwd=project_dir, capture_output=True, text=True, timeout=60
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return result.stdout or ""

harness/services/retention.py

@@ -0,0 +1,97 @@
+"""Ledger retention service — compact old sessions by pruning bulky run events.
+
+Token and tool_result events are large and reconstructible from the transcript
+artifact (written by ``_persist_artifacts`` in engine.py). After compaction the
+essential audit trail (message, status, cost, adapter_meta, tool_call, error,
+artifact) remains intact.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import delete, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.models.enums import RunEventType, SessionStatus
+from harness.models.run import Run
+from harness.models.run_event import RunEvent
+from harness.models.session import Session
+
+# Statuses considered terminal — only these sessions are eligible for compaction.
+_TERMINAL_STATUSES = (
+    SessionStatus.completed,
+    SessionStatus.failed,
+    SessionStatus.archived,
+)
+
+# Event types that are bulky and reconstructible from the transcript artifact.
+_PURGEABLE_TYPES = (
+    RunEventType.token,
+    RunEventType.tool_result,
+)
+
+
+@dataclass
+class CompactReport:
+    sessions: int
+    events_deleted: int
+
+
+async def compact_sessions(
+    db: AsyncSession,
+    *,
+    older_than_days: int,
+    dry_run: bool = False,
+) -> CompactReport:
+    """Delete (or count) bulky run events from old, terminal sessions.
+
+    Target sessions: terminal status (completed/failed/archived) AND
+    ``updated_at`` older than the horizon (``now(UTC) - older_than_days``).
+
+    Purges ``token`` and ``tool_result`` events only — keeps message/status/
+    cost/adapter_meta/tool_call/error/artifact.
+
+    When ``dry_run`` is True, counts the events that *would* be deleted without
+    actually deleting them.
+
+    Returns a :class:`CompactReport` with the session count and event count.
+    """
+    horizon = datetime.now(UTC) - timedelta(days=older_than_days)
+
+    # Resolve qualifying session ids.
+    session_ids_stmt = (
+        select(Session.id)
+        .where(Session.status.in_(_TERMINAL_STATUSES))
+        .where(Session.updated_at < horizon)
+    )
+    session_ids = list((await db.execute(session_ids_stmt)).scalars())
+
+    if not session_ids:
+        return CompactReport(sessions=0, events_deleted=0)
+
+    # Resolve qualifying run ids for those sessions.
+    run_ids_stmt = select(Run.id).where(Run.session_id.in_(session_ids))
+    run_ids = list((await db.execute(run_ids_stmt)).scalars())
+
+    if not run_ids:
+        return CompactReport(sessions=len(session_ids), events_deleted=0)
+
+    # Count purgeable events.
+    count_stmt = (
+        select(func.count())
+        .select_from(RunEvent)
+        .where(RunEvent.run_id.in_(run_ids))
+        .where(RunEvent.type.in_(_PURGEABLE_TYPES))
+    )
+    events_deleted = (await db.execute(count_stmt)).scalar_one()
+
+    if not dry_run and events_deleted > 0:
+        await db.execute(
+            delete(RunEvent)
+            .where(RunEvent.run_id.in_(run_ids))
+            .where(RunEvent.type.in_(_PURGEABLE_TYPES))
+        )
+        await db.commit()
+
+    return CompactReport(sessions=len(session_ids), events_deleted=events_deleted)