cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/state/retention.py

@@ -0,0 +1,218 @@
+"""Spool retention and purge (docs/privacy.md, "Retention" and "Purge command contract").
+
+Defaults: 14 days or 50 MB per session, whichever comes first. Everything here touches only
+``<git-common-dir>/cursorfleet/``; committed ``.cursorfleet/`` and ``.cursor/`` are never
+reachable from these functions. Deletion is ordinary file removal, not secure wiping.
+Planning is separate from applying so ``--dry-run`` shares the exact same code path.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from contextlib import suppress
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+from cursorfleet.events.ids import fs_name_for
+from cursorfleet.state.runtime import RuntimePaths
+from cursorfleet.state.spool import CAPPED_MARKER, SPOOL_SUFFIX
+
+DEFAULT_MAX_AGE_DAYS = 14
+DEFAULT_MAX_SESSION_MB = 50
+
+_DURATION = re.compile(r"^(\d{1,6})([smhdw])$")
+_UNITS = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}
+
+
+def parse_duration(text: str) -> timedelta:
+    """Parse ``30m``, ``12h``, ``7d``, ``2w`` (and ``s``). Raises ``ValueError`` otherwise."""
+    match = _DURATION.match(text.strip().lower())
+    if match is None:
+        msg = f"invalid duration {text!r}; use e.g. 90m, 12h, 7d, 2w"
+        raise ValueError(msg)
+    return timedelta(seconds=int(match.group(1)) * _UNITS[match.group(2)])
+
+
+@dataclass
+class PurgePlan:
+    """What would be removed. Paths are absolute and under the runtime root."""
+
+    files: list[str] = field(default_factory=list)
+    file_bytes: int = 0
+    session_dirs: list[str] = field(default_factory=list)  # removed entirely (incl. markers)
+    partial_sessions: int = 0  # sessions that survive but lose some segments
+    clear_markers: list[str] = field(default_factory=list)
+    remove_projection: bool = False
+    rotate_key: bool = False
+    remove_quarantine: bool = False
+
+    @property
+    def sessions(self) -> int:
+        return len(self.session_dirs) + self.partial_sessions
+
+    @property
+    def empty(self) -> bool:
+        return not (
+            self.files
+            or self.session_dirs
+            or self.clear_markers
+            or self.remove_projection
+            or self.rotate_key
+            or self.remove_quarantine
+        )
+
+
+@dataclass
+class PurgeReport:
+    sessions: int = 0
+    files: int = 0
+    bytes: int = 0
+    projection_removed: bool = False
+    key_rotated: bool = False
+    needs_reindex: bool = False
+    errors: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class _SessionDir:
+    path: str
+    files: tuple[tuple[str, int, float], ...]  # (path, size, mtime), oldest first
+
+    @property
+    def size(self) -> int:
+        return sum(size for _p, size, _m in self.files)
+
+    @property
+    def newest(self) -> float:
+        return max((m for _p, _s, m in self.files), default=0.0)
+
+
+def _scan_sessions(paths: RuntimePaths) -> list[_SessionDir]:
+    found: list[_SessionDir] = []
+    try:
+        with os.scandir(paths.spool) as entries:
+            directories = sorted(e.path for e in entries if e.is_dir(follow_symlinks=False))
+    except OSError:
+        return found
+    for directory in directories:
+        files: list[tuple[str, int, float]] = []
+        try:
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    if entry.name.endswith(SPOOL_SUFFIX) and entry.is_file(follow_symlinks=False):
+                        stat = entry.stat(follow_symlinks=False)
+                        files.append((entry.path, stat.st_size, stat.st_mtime))
+        except OSError:
+            continue
+        files.sort(key=lambda f: (f[2], f[0]))
+        found.append(_SessionDir(directory, tuple(files)))
+    return found
+
+
+def _whole_session(plan: PurgePlan, session: _SessionDir) -> None:
+    plan.session_dirs.append(session.path)
+    plan.files.extend(p for p, _s, _m in session.files)
+    plan.file_bytes += session.size
+
+
+def plan_purge(  # noqa: PLR0913
+    paths: RuntimePaths,
+    *,
+    now: datetime,
+    older_than: timedelta | None = None,
+    session: str | None = None,
+    everything: bool = False,
+    max_age_days: int = DEFAULT_MAX_AGE_DAYS,
+    max_session_mb: int = DEFAULT_MAX_SESSION_MB,
+) -> PurgePlan:
+    """Plan a purge. With no selector the configured retention is applied."""
+    plan = PurgePlan()
+    sessions = _scan_sessions(paths)
+    if everything:
+        for item in sessions:
+            _whole_session(plan, item)
+        plan.remove_projection = os.path.isdir(paths.index_dir)
+        plan.rotate_key = os.path.exists(paths.hmac_key)
+        plan.remove_quarantine = os.path.isdir(paths.quarantine)
+        return plan
+    if session is not None:
+        target = os.path.join(paths.spool, fs_name_for(session))
+        for item in sessions:
+            if item.path == target:
+                _whole_session(plan, item)
+        return plan
+    now_ts = now.timestamp()
+    cap = max_session_mb * 1024 * 1024
+    age_limit = older_than if older_than is not None else timedelta(days=max_age_days)
+    for item in sessions:
+        if item.files and now_ts - item.newest > age_limit.total_seconds():
+            _whole_session(plan, item)
+            continue
+        if older_than is None and item.size > cap:
+            _plan_over_cap(plan, item, cap)
+        elif older_than is None and os.path.lexists(os.path.join(item.path, CAPPED_MARKER)):
+            plan.clear_markers.append(os.path.join(item.path, CAPPED_MARKER))
+    return plan
+
+
+def _plan_over_cap(plan: PurgePlan, item: _SessionDir, cap: int) -> None:
+    remaining = item.size
+    removed_any = False
+    for path, size, _mtime in item.files:  # oldest first; active files are newest anyway
+        if remaining <= cap:
+            break
+        plan.files.append(path)
+        plan.file_bytes += size
+        remaining -= size
+        removed_any = True
+    if removed_any:
+        plan.partial_sessions += 1
+    marker = os.path.join(item.path, CAPPED_MARKER)
+    if remaining < cap and os.path.lexists(marker):
+        plan.clear_markers.append(marker)
+
+
+def _remove_file(path: str, report: PurgeReport) -> bool:
+    try:
+        os.remove(path)
+    except FileNotFoundError:
+        return True
+    except OSError as exc:
+        report.errors.append(f"{os.path.basename(path)}: {exc.strerror or exc}")
+        return False
+    return True
+
+
+def apply_plan(paths: RuntimePaths, plan: PurgePlan) -> PurgeReport:
+    """Execute ``plan``. Best effort: failures are collected, never raised."""
+    report = PurgeReport()
+    root = os.path.realpath(paths.root)
+    for path in plan.files:
+        if not os.path.realpath(path).startswith(root + os.sep):
+            report.errors.append("refused path outside the runtime directory")
+            continue
+        try:
+            size = os.lstat(path).st_size
+        except OSError:
+            size = 0
+        if _remove_file(path, report):
+            report.files += 1
+            report.bytes += size
+    for marker in plan.clear_markers:
+        _remove_file(marker, report)
+    for directory in plan.session_dirs:
+        _remove_file(os.path.join(directory, CAPPED_MARKER), report)
+        with suppress(OSError):  # not empty (e.g. a hook recreated a file): leave it
+            os.rmdir(directory)
+    report.sessions = plan.sessions
+    report.needs_reindex = bool(plan.files) or plan.remove_projection
+    if plan.remove_projection:
+        shutil.rmtree(paths.index_dir, ignore_errors=True)
+        report.projection_removed = True
+    if plan.rotate_key:
+        report.key_rotated = _remove_file(paths.hmac_key, report)
+    if plan.remove_quarantine:
+        shutil.rmtree(paths.quarantine, ignore_errors=True)
+    return report

cursorfleet/state/run_builder.py

@@ -0,0 +1,136 @@
+"""Build task/run snapshots from sessions, artifacts, and optional run metadata."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from cursorfleet.state.artifact_scan import ArtifactRecord
+from cursorfleet.state.models import Lane, SessionAcc, SessionView, utc
+from cursorfleet.state.run_model import (
+    Confidence,
+    ParticipantGroup,
+    ParticipantInstance,
+    RunSnapshot,
+)
+
+DEFAULT_STALE_AFTER_S = 900
+
+
+def _is_stale(view: SessionView, now: datetime, stale_after_s: int) -> bool:
+    if view.lane in (Lane.DONE.value, Lane.UNKNOWN.value):
+        return False
+    if view.last_ts is None:
+        return True
+    return (utc(now) - utc(view.last_ts)).total_seconds() > stale_after_s
+
+
+def build_active_run(  # noqa: PLR0913, PLR0912
+    *,
+    task_slug: str,
+    run_id: str,
+    sessions: dict[str, SessionAcc],
+    session_views: dict[str, SessionView],
+    records: list[ArtifactRecord],
+    linked_session_ids: frozenset[str] | None = None,
+    now: datetime,
+    stale_after_s: int = DEFAULT_STALE_AFTER_S,
+) -> RunSnapshot:
+    """In-memory Active Run for one task slug (B1 prototype)."""
+    task_records = [r for r in records if r.task == task_slug]
+    roles_from_declared = {r.author_role for r in task_records}
+
+    groups: dict[str, ParticipantGroup] = {}
+    unassociated: list[str] = []
+    suggested: list[str] = []
+
+    for sid, sview in session_views.items():
+        if _is_stale(sview, now, stale_after_s) and sid not in (linked_session_ids or ()):
+            continue
+        matched = False
+        for aview in sview.agents:
+            acc = sessions[sid].agents[aview.key]
+            role = acc.role or aview.key
+            if role in roles_from_declared or sid in (linked_session_ids or ()):
+                matched = True
+                inst = ParticipantInstance(
+                    session_id=sid,
+                    agent_key=aview.key,
+                    role=acc.role,
+                    lane=aview.lane,
+                    lane_basis=aview.lane_basis,
+                    last_ts=aview.last_ts,
+                    stale=aview.stale,
+                )
+                grp = groups.get(role)
+                if grp is None:
+                    groups[role] = ParticipantGroup(
+                        role=role,
+                        summary_lane=aview.lane,
+                        confidence="explicit" if sid in (linked_session_ids or ()) else "inferred",
+                        instances=[inst],
+                    )
+                else:
+                    grp.instances.append(inst)
+                    if aview.lane == Lane.BLOCKED.value or grp.summary_lane != aview.lane:
+                        grp.conflict = True
+        if not matched and not _is_stale(sview, now, stale_after_s):
+            if roles_from_declared:
+                suggested.append(sid)
+            else:
+                unassociated.append(sid)
+
+    for role in roles_from_declared:
+        if role not in groups:
+            blockers = sum(
+                1 for r in task_records if r.author_role == role and r.kind == "blocker.raised"
+            )
+            groups[role] = ParticipantGroup(
+                role=role,
+                summary_lane=Lane.UNKNOWN.value,
+                confidence="declared",
+                declared_blockers=blockers,
+            )
+
+    if linked_session_ids:
+        confidence: Confidence = "explicit"
+    elif task_records:
+        confidence = "declared"
+    else:
+        confidence = "inferred"
+    primary_wt = None
+    branch = None
+    commit = None
+    linked = linked_session_ids or frozenset()
+    if linked:
+        git_pairs: list[tuple[str, SessionView]] = [
+            (sid, session_views[sid]) for sid in linked if sid in session_views
+        ]
+    else:
+        git_pairs = list(session_views.items())
+    for _sid, sview in git_pairs:
+        if sview.worktree_ids and primary_wt is None:
+            primary_wt = sview.worktree_ids[0]
+        if sview.branch and branch is None:
+            branch = sview.branch
+        if sview.commit and commit is None:
+            commit = sview.commit
+
+    return RunSnapshot(
+        run_id=run_id,
+        task_slug=task_slug,
+        confidence=confidence,
+        primary_worktree_id=primary_wt,
+        branch=branch,
+        commit=commit,
+        groups=sorted(groups.values(), key=lambda g: g.role),
+        unassociated_session_ids=sorted(unassociated),
+        suggested_session_ids=sorted(suggested),
+    )
+
+
+def pick_primary_task(records: list[ArtifactRecord], *, now: datetime) -> str | None:
+    """Most recently declared task slug, if any."""
+    if not records:
+        return None
+    latest = max(records, key=lambda r: (r.created, r.path))
+    return latest.task

cursorfleet/state/run_model.py

@@ -0,0 +1,43 @@
+"""Task/run view models (M2.5). Pure data; no I/O."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal
+
+Confidence = Literal["explicit", "declared", "inferred"]
+
+
+@dataclass(frozen=True)
+class ParticipantInstance:
+    session_id: str
+    agent_key: str
+    role: str | None
+    lane: str
+    lane_basis: str
+    last_ts: datetime | None
+    stale: bool = False
+
+
+@dataclass
+class ParticipantGroup:
+    role: str
+    summary_lane: str
+    confidence: Confidence
+    instances: list[ParticipantInstance] = field(default_factory=list)
+    declared_blockers: int = 0
+    conflict: bool = False
+
+
+@dataclass
+class RunSnapshot:
+    run_id: str
+    task_slug: str
+    confidence: Confidence
+    primary_worktree_id: str | None
+    branch: str | None
+    commit: str | None
+    groups: list[ParticipantGroup] = field(default_factory=list)
+    unassociated_session_ids: list[str] = field(default_factory=list)
+    suggested_session_ids: list[str] = field(default_factory=list)

cursorfleet/state/run_store.py

@@ -0,0 +1,95 @@
+"""Run metadata under ``<git-common-dir>/cursorfleet/runs/`` (B2)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+RUNS_SCHEMA = "cursorfleet.run/0.1"
+
+
+@dataclass
+class RunRecord:
+    run_id: str
+    task_slug: str
+    created_at: str
+    archived: bool = False
+    session_ids: list[str] = field(default_factory=list)
+    schema: str = RUNS_SCHEMA
+
+    def to_json(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["schema"] = RUNS_SCHEMA
+        return data
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> RunRecord:
+        return cls(
+            run_id=str(data["run_id"]),
+            task_slug=str(data["task_slug"]),
+            created_at=str(data.get("created_at", datetime.now(tz=UTC).isoformat())),
+            archived=bool(data.get("archived", False)),
+            session_ids=[str(s) for s in data.get("session_ids", [])],
+        )
+
+
+def runs_dir(runtime_root: str) -> Path:
+    return Path(runtime_root) / "runs"
+
+
+def _run_path(root: str, run_id: str) -> Path:
+    safe = run_id.replace("/", "_").replace("\\", "_")
+    return runs_dir(root) / f"{safe}.json"
+
+
+def list_runs(runtime_root: str) -> list[RunRecord]:
+    directory = runs_dir(runtime_root)
+    if not directory.is_dir():
+        return []
+    out: list[RunRecord] = []
+    for path in sorted(directory.glob("*.json")):
+        if path.name == "index.json":
+            continue
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                out.append(RunRecord.from_json(data))
+        except (OSError, json.JSONDecodeError, KeyError, TypeError):
+            continue
+    return out
+
+
+def load_run(runtime_root: str, run_id: str) -> RunRecord | None:
+    path = _run_path(runtime_root, run_id)
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return RunRecord.from_json(data)
+
+
+def save_run(runtime_root: str, record: RunRecord) -> None:
+    directory = runs_dir(runtime_root)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = _run_path(runtime_root, record.run_id)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(record.to_json(), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def attach_session(runtime_root: str, run_id: str, session_id: str) -> bool:
+    record = load_run(runtime_root, run_id)
+    if record is None or record.archived:
+        return False
+    if session_id not in record.session_ids:
+        record.session_ids.append(session_id)
+        save_run(runtime_root, record)
+    return True