cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/events/kinds.py

@@ -0,0 +1,132 @@
+"""Event vocabulary: enums and constants. Stdlib only (shared with the hook hot path).
+
+There is deliberately no kind for thoughts, prompts or responses
+(ADR 0004). Adding one needs a superseding ADR.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+SCHEMA_VERSION = "1.0"
+
+# Stored in place of any path outside the workspace roots.
+EXTERNAL_PATH = "<external>"
+
+# Hard bounds shared by the models and the stdlib sanitizer.
+COMMAND_DISPLAY_MAX_CHARS = 200
+MAX_PATHS_PER_EVENT = 200
+
+
+class EventKind(StrEnum):
+    SESSION_STARTED = "session.started"
+    SESSION_STOPPED = "session.stopped"
+    STATUS_CHANGED = "status.changed"
+    TOOL_STARTED = "tool.started"
+    TOOL_COMPLETED = "tool.completed"
+    TOOL_FAILED = "tool.failed"
+    FILE_CHANGED = "file.changed"
+    TEST_COMPLETED = "test.completed"  # legacy spool lines; prefer VERIFICATION_OBSERVED
+    VERIFICATION_OBSERVED = "verification.observed"
+    SUBAGENT_STARTED = "subagent.started"
+    SUBAGENT_STOPPED = "subagent.stopped"
+    CONTEXT_COMPACTED = "context.compacted"
+    PLAN_CREATED = "plan.created"
+    HANDOFF_CREATED = "handoff.created"
+    BLOCKER_RAISED = "blocker.raised"
+    GATE_CHANGED = "gate.changed"
+    CONTEXT_LOADED = "context.loaded"
+
+
+class Source(StrEnum):
+    """How we know an event happened. Never display self_reported as fact."""
+
+    OBSERVED = "observed"  # directly from a Cursor hook payload
+    SELF_REPORTED = "self_reported"  # declared by an agent (artifact or emit CLI)
+    DERIVED = "derived"  # computed by CursorFleet from observed events or git
+
+
+class Producer(StrEnum):
+    CURSOR_HOOK = "cursor_hook"
+    WORK_ARTIFACT = "work_artifact"
+    EMIT_CLI = "emit_cli"
+    INDEXER = "indexer"
+
+
+class Risk(StrEnum):
+    """Informational label only; v0.1 never acts on it."""
+
+    NONE = "none"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class Attribution(StrEnum):
+    """How confidently the event is tied to ``agent_role``/``agent_instance_id``.
+
+    PROVISIONAL (ADR 0001 Q1): tool hooks may not identify the subagent, so most
+    tool events may legitimately be ``unknown`` or ``inferred``.
+    """
+
+    EXACT = "exact"  # identity present in the payload itself
+    INFERRED = "inferred"  # temporal window, worktree or tool_use_id linkage
+    UNKNOWN = "unknown"
+
+
+class Outcome(StrEnum):
+    OK = "ok"
+    FAILED = "failed"
+    TIMEOUT = "timeout"
+    PERMISSION_DENIED = "permission_denied"
+    INTERRUPTED = "interrupted"
+    UNKNOWN = "unknown"
+
+
+class AgentStatus(StrEnum):
+    IDLE = "idle"
+    WORKING = "working"
+    WAITING = "waiting"
+    BLOCKED = "blocked"
+    DONE = "done"
+    ERROR = "error"
+    UNKNOWN = "unknown"
+
+
+class GateState(StrEnum):
+    PASSING = "passing"
+    FAILING = "failing"
+    STALE = "stale"
+    UNKNOWN = "unknown"
+
+
+class PathOp(StrEnum):
+    CREATED = "created"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    UNKNOWN = "unknown"
+
+
+# Kinds Cursor cannot observe: they may only come from an agent declaration.
+SELF_REPORT_ONLY_KINDS: frozenset[EventKind] = frozenset(
+    {
+        EventKind.PLAN_CREATED,
+        EventKind.HANDOFF_CREATED,
+        EventKind.BLOCKER_RAISED,
+        EventKind.CONTEXT_LOADED,
+    }
+)
+
+# Kinds an agent may declare. Tool, file and subagent facts cannot be self-reported.
+SELF_REPORTABLE_KINDS: frozenset[EventKind] = SELF_REPORT_ONLY_KINDS | {EventKind.STATUS_CHANGED}
+
+VERIFICATION_KINDS: frozenset[EventKind] = frozenset(
+    {EventKind.TEST_COMPLETED, EventKind.VERIFICATION_OBSERVED}
+)
+
+
+def normalize_event_kind(kind: EventKind) -> EventKind:
+    """Map legacy verification kinds to the canonical enum member."""
+    if kind is EventKind.TEST_COMPLETED:
+        return EventKind.VERIFICATION_OBSERVED
+    return kind

cursorfleet/events/models.py

@@ -0,0 +1,213 @@
+"""Versioned event model (schema_version "1.0"): the source of truth for event.schema.json.
+
+The stdlib-only hook hot path does NOT import this module. It re-implements
+validation with the stdlib and is contract-tested against these models
+(docs/architecture.md). Every model forbids extra keys, so an unlisted field
+(a prompt, an email, a transcript path) can never ride along in a valid event.
+
+PROVISIONAL (ADR 0001 Q1, Q2): ``agent_role``, ``agent_instance_id``,
+``agent_id`` and ``attribution`` depend on what subagent tool hooks reveal.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Self
+
+from pydantic import AfterValidator, AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+
+from cursorfleet.events.ids import AGENT_ID_PATTERN, SAFE_ID_PATTERN, ULID_PATTERN, derive_agent_id
+from cursorfleet.events.kinds import (
+    COMMAND_DISPLAY_MAX_CHARS,
+    MAX_PATHS_PER_EVENT,
+    SCHEMA_VERSION,
+    SELF_REPORT_ONLY_KINDS,
+    SELF_REPORTABLE_KINDS,
+    AgentStatus,
+    Attribution,
+    EventKind,
+    GateState,
+    Outcome,
+    PathOp,
+    Producer,
+    Risk,
+    Source,
+)
+from cursorfleet.events.pathcheck import check_relative_posix
+
+
+def _printable(value: str) -> str:
+    if not value.isprintable():
+        msg = "must not contain control, bidi-override or other non-printable characters"
+        raise ValueError(msg)
+    return value
+
+
+def _relative_or_external(value: str) -> str:
+    return check_relative_posix(value, allow_external=True)
+
+
+SafeId = Annotated[str, Field(pattern=SAFE_ID_PATTERN, max_length=128)]
+AgentId = Annotated[str, Field(pattern=AGENT_ID_PATTERN, max_length=257)]
+Ulid = Annotated[str, Field(pattern=ULID_PATTERN, min_length=26, max_length=26)]
+VersionStr = Annotated[str, Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._+\-]{0,63}$", max_length=64)]
+Printable = Annotated[str, AfterValidator(_printable)]
+NonNegInt = Annotated[int, Field(ge=0, le=10**12, strict=True)]
+EventPath = Annotated[str, AfterValidator(_relative_or_external)]
+
+_STRICT = ConfigDict(extra="forbid", frozen=True, str_strip_whitespace=False)
+
+
+class SanitizedPath(BaseModel):
+    """A path reduced to a workspace-relative POSIX string, or ``<external>``."""
+
+    model_config = _STRICT
+
+    path: EventPath = Field(
+        description="Workspace-relative, symlink-resolved, '/' separated; "
+        "'<external>' for anything outside the workspace roots."
+    )
+    op: PathOp = PathOp.UNKNOWN
+
+
+class SanitizedCommand(BaseModel):
+    """A shell command reduced to non-sensitive facts. Never the raw command line."""
+
+    model_config = _STRICT
+
+    argv0: Annotated[str, Field(pattern=r"^[A-Za-z0-9_][A-Za-z0-9._+\-]{0,63}$")] = Field(
+        description="Executable basename only (no directory)."
+    )
+    subcommand: Annotated[str, Field(pattern=r"^[a-z][a-z0-9:_\-]{0,63}$")] | None = Field(
+        default=None, description="First non-flag word for known multi-command tools."
+    )
+    exit_code: Annotated[int, Field(ge=-1024, le=1024, strict=True)] | None = None
+    duration_ms: NonNegInt | None = None
+    display: Annotated[Printable, Field(max_length=COMMAND_DISPLAY_MAX_CHARS)] | None = Field(
+        default=None,
+        description="Redacted and truncated single-line display string (best effort, "
+        "not a security guarantee).",
+    )
+    display_truncated: bool = False
+    command_hash: Annotated[str, Field(pattern=r"^[0-9a-f]{16,64}$")] | None = Field(
+        default=None,
+        description="Keyed (HMAC) hash of the normalized argv for dedupe; key is local.",
+    )
+
+
+class GateRef(BaseModel):
+    """Display-only gate signal (v0.1 never enforces gates)."""
+
+    model_config = _STRICT
+
+    name: Annotated[str, Field(pattern=r"^[a-z][a-z0-9_\-]{0,31}$")]
+    state: GateState
+
+
+class Metrics(BaseModel):
+    """Bounded counters Cursor exposes. Token usage appears only via compaction."""
+
+    model_config = _STRICT
+
+    duration_ms: NonNegInt | None = None
+    tool_call_count: NonNegInt | None = None
+    message_count: NonNegInt | None = None
+    loop_count: NonNegInt | None = None
+    context_usage_percent: Annotated[float, Field(ge=0, le=1000)] | None = None
+    context_tokens: NonNegInt | None = None
+    context_window_size: NonNegInt | None = None
+
+
+class Event(BaseModel):
+    """One normalized CursorFleet event (schema_version "1.0")."""
+
+    model_config = _STRICT
+
+    schema_version: Literal["1.0"] = SCHEMA_VERSION  # type: ignore[assignment]
+    event_id: Ulid = Field(description="ULID-style id (26 Crockford base32 chars).")
+    ts: AwareDatetime = Field(description="Timezone-aware event time.")
+    producer: Producer
+    producer_version: VersionStr
+    cursor_version: VersionStr | None = Field(
+        default=None, description="Cursor version from the payload; absent for non-hook producers."
+    )
+    source: Source = Field(description="observed | self_reported | derived. Show it in the UI.")
+    kind: EventKind
+
+    session_id: SafeId = Field(description="Cursor conversation_id.")
+    generation_id: SafeId | None = None
+    agent_role: SafeId | None = Field(
+        default=None,
+        description="Roster id when subagent_type maps to it, else the raw subagent_type. "
+        "PROVISIONAL (ADR 0001 Q2).",
+    )
+    agent_instance_id: SafeId | None = Field(
+        default=None, description="Cursor subagent_id. PROVISIONAL (ADR 0001 Q1)."
+    )
+    agent_id: AgentId | None = Field(
+        default=None,
+        description="Derived as 'role#instance'; if given it must equal the derived value.",
+    )
+    attribution: Attribution = Attribution.UNKNOWN
+
+    risk: Risk = Risk.NONE
+    worktree_id: SafeId | None = None
+    branch: Annotated[Printable, Field(min_length=1, max_length=255)] | None = None
+    commit: Annotated[str, Field(pattern=r"^[0-9a-f]{7,64}$")] | None = None
+    issue_ref: Annotated[str, Field(pattern=r"^[A-Za-z0-9_.\-/#]{1,100}$")] | None = None
+
+    tool_name: Annotated[str, Field(pattern=r"^[A-Za-z0-9_:.\-]{1,128}$")] | None = None
+    tool_use_id: SafeId | None = Field(
+        default=None,
+        description="Opaque Cursor tool_use_id (tool hooks) or tool_call_id (subagentStart); "
+        "pairs started/completed and is the candidate Task-to-subagent link. "
+        "PROVISIONAL (ADR 0001 section B).",
+    )
+    hook: Annotated[str, Field(pattern=r"^[A-Za-z][A-Za-z0-9]{0,63}$")] | None = Field(
+        default=None,
+        description="Cursor hook_event_name that produced the event; lets the reducer "
+        "de-duplicate overlapping hooks (preToolUse vs beforeShellExecution).",
+    )
+    outcome: Outcome | None = None
+    status: AgentStatus | None = None
+    gate: GateRef | None = None
+    command: SanitizedCommand | None = None
+    paths: Annotated[tuple[SanitizedPath, ...], Field(max_length=MAX_PATHS_PER_EVENT)] = ()
+    metrics: Metrics | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _fill_agent_id(cls, data: Any) -> Any:
+        if isinstance(data, dict) and data.get("agent_id") is None:
+            derived = derive_agent_id(data.get("agent_role"), data.get("agent_instance_id"))
+            if derived is not None:
+                return {**data, "agent_id": derived}
+        return data
+
+    @model_validator(mode="after")
+    def _check_consistency(self) -> Self:
+        derived = derive_agent_id(self.agent_role, self.agent_instance_id)
+        if self.agent_id != derived:
+            msg = "agent_id must equal the value derived from agent_role and agent_instance_id"
+            raise ValueError(msg)
+        if self.kind in SELF_REPORT_ONLY_KINDS and self.source is not Source.SELF_REPORTED:
+            msg = f"{self.kind.value} is not observable by Cursor hooks; use source=self_reported"
+            raise ValueError(msg)
+        if self.source is Source.SELF_REPORTED and self.kind not in SELF_REPORTABLE_KINDS:
+            msg = f"{self.kind.value} cannot be self-reported"
+            raise ValueError(msg)
+        if (self.kind is EventKind.GATE_CHANGED) != (self.gate is not None):
+            msg = "gate is required for, and only allowed on, gate.changed"
+            raise ValueError(msg)
+        if self.kind is EventKind.FILE_CHANGED and not self.paths:
+            msg = "file.changed requires at least one path"
+            raise ValueError(msg)
+        return self
+
+
+__all__ = [
+    "Event",
+    "GateRef",
+    "Metrics",
+    "SanitizedCommand",
+    "SanitizedPath",
+]

cursorfleet/events/pathcheck.py

@@ -0,0 +1,45 @@
+"""Stdlib-only validation for workspace-relative POSIX paths."""
+
+from __future__ import annotations
+
+import re
+
+from cursorfleet.events.kinds import EXTERNAL_PATH
+
+_DRIVE = re.compile(r"^[A-Za-z]:")
+MAX_PATH_CHARS = 1024
+
+
+def check_relative_posix(value: str, *, allow_external: bool = False) -> str:
+    """Return ``value`` if it is a safe workspace-relative POSIX path, else raise ValueError.
+
+    Rejects absolute paths, drive letters, backslashes, empty/``.``/``..`` segments
+    and non-printable characters (control, bidi override, line separators).
+    """
+    if allow_external and value == EXTERNAL_PATH:
+        return value
+    if not value or len(value) > MAX_PATH_CHARS:
+        msg = "path must be 1..1024 characters"
+        raise ValueError(msg)
+    if not value.isprintable():
+        msg = "path contains non-printable characters"
+        raise ValueError(msg)
+    if "\\" in value or value.startswith("/") or _DRIVE.match(value):
+        msg = "path must be workspace-relative with '/' separators"
+        raise ValueError(msg)
+    if any(part in {"", ".", ".."} for part in value.split("/")):
+        msg = "path must not contain empty, '.' or '..' segments"
+        raise ValueError(msg)
+    return value
+
+
+def check_not_in_git_dir(value: str) -> str:
+    """Raise ``ValueError`` if ``value`` has a ``.git`` segment (any case); else return it.
+
+    For locations CursorFleet *writes or deletes* (work dir, lockfile paths): a hostile
+    config or lockfile must not be able to aim those operations at repository internals.
+    """
+    if any(part.lower() == ".git" for part in value.split("/")):
+        msg = "path must not be inside .git"
+        raise ValueError(msg)
+    return value

cursorfleet/git/collector.py

@@ -0,0 +1,226 @@
+"""Read-only git/worktree collector. No fetch, no mutation, argv lists, timeouts everywhere.
+
+Produces a :class:`GitSnapshot` that is useful with ZERO hook telemetry ("git-only"):
+branch, HEAD, dirty file count, ahead/behind versus the EXISTING upstream ref (we never
+fetch, so it can lag the remote), stale detection and the last commit time. Linking a
+worktree to an owning session/task is done by the caller from state (``activity`` and
+``worktree_id``), never by this module guessing.
+
+Cursor creates, discovers and deletes worktrees itself (ADR 0001 A8), so a worktree may
+vanish between two calls; every field degrades to ``None`` instead of raising.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+from cursorfleet.events.ids import worktree_id_for
+from cursorfleet.git.runner import (
+    DEFAULT_TIMEOUT_S,
+    GitResult,
+    GitUnavailable,
+    NotAGitRepo,
+    git_common_dir,
+    run_git,
+)
+from cursorfleet.git.worktrees import WorktreeEntry, parse_porcelain
+
+DEFAULT_STALE_AFTER_HOURS = 72
+
+
+@dataclass(frozen=True)
+class WorktreeSnapshot:
+    path: str  # as reported by git
+    real_path: str | None  # realpath if it exists
+    worktree_id: str | None
+    is_main: bool
+    exists: bool
+    branch: str | None
+    head: str | None
+    detached: bool
+    bare: bool
+    locked: bool
+    prunable: bool
+    dirty_count: int | None
+    upstream: bool  # an upstream ref is configured and resolvable
+    ahead: int | None
+    behind: int | None
+    last_commit_ts: datetime | None
+    stale: bool
+    stale_reasons: tuple[str, ...]
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class GitSnapshot:
+    available: bool
+    error: str | None
+    common_dir: str | None
+    collected_at: datetime
+    worktrees: tuple[WorktreeSnapshot, ...] = field(default_factory=tuple)
+
+
+def _empty(now: datetime, error: str, common_dir: str | None = None) -> GitSnapshot:
+    return GitSnapshot(False, error, common_dir, now)
+
+
+def count_status_entries(raw: bytes) -> int:
+    """Count entries in ``git status --porcelain=v1 -z`` output (rename/copy have 2 fields)."""
+    fields = raw.split(b"\0")
+    count = 0
+    index = 0
+    while index < len(fields):
+        entry = fields[index]
+        index += 1
+        if not entry:
+            continue
+        count += 1
+        if len(entry) >= 2 and (entry[:1] in b"RC" or entry[1:2] in b"RC"):
+            index += 1  # the original path follows as a separate field
+    return count
+
+
+def _safe_run(args: list[str], cwd: str, timeout: float) -> GitResult | None:
+    try:
+        return run_git(args, cwd, timeout=timeout)
+    except GitUnavailable:
+        return None
+
+
+def _parse_ahead_behind(text: str) -> tuple[int, int] | None:
+    parts = text.split()
+    if len(parts) != 2 or not all(p.isdigit() for p in parts):
+        return None
+    behind, ahead = int(parts[0]), int(parts[1])  # left = upstream-only, right = HEAD-only
+    return ahead, behind
+
+
+def _probe(  # noqa: PLR0913
+    entry: WorktreeEntry,
+    *,
+    is_main: bool,
+    now: datetime,
+    stale_after: timedelta,
+    activity: datetime | None,
+    timeout: float,
+    ahead_behind: bool,
+) -> WorktreeSnapshot:
+    reasons: list[str] = []
+    error: str | None = None
+    exists = os.path.isabs(entry.path) and os.path.isdir(entry.path)
+    real = os.path.realpath(entry.path) if exists else None
+    dirty = ahead = behind = None
+    upstream = False
+    last_commit: datetime | None = None
+    if not exists:
+        reasons.append("missing_path")
+    if entry.prunable:
+        reasons.append("prunable")
+    probe = exists and not entry.bare and not entry.prunable and real is not None
+    if probe and real is not None:
+        status = _safe_run(
+            ["status", "--porcelain=v1", "-z", "--untracked-files=normal"], real, timeout
+        )
+        if status is not None and status.ok:
+            dirty = count_status_entries(status.stdout)
+        else:
+            error = "status_failed"
+        if ahead_behind and not entry.detached:
+            counts = _safe_run(
+                ["rev-list", "--left-right", "--count", "@{upstream}...HEAD"], real, timeout
+            )
+            if counts is not None and counts.ok:
+                parsed = _parse_ahead_behind(counts.text())
+                if parsed is not None:
+                    upstream = True
+                    ahead, behind = parsed
+        stamp = _safe_run(["log", "-1", "--format=%ct", "HEAD"], real, timeout)
+        if stamp is not None and stamp.ok and stamp.text().strip().isdigit():
+            last_commit = datetime.fromtimestamp(int(stamp.text().strip()), UTC)
+    latest = max((t for t in (activity, last_commit) if t is not None), default=None)
+    if probe and latest is not None and now - latest > stale_after:
+        reasons.append("inactive")
+    return WorktreeSnapshot(
+        path=entry.path,
+        real_path=real,
+        worktree_id=worktree_id_for(real) if real is not None else None,
+        is_main=is_main,
+        exists=exists,
+        branch=entry.branch,
+        head=entry.head,
+        detached=entry.detached,
+        bare=entry.bare,
+        locked=entry.locked,
+        prunable=entry.prunable,
+        dirty_count=dirty,
+        upstream=upstream,
+        ahead=ahead,
+        behind=behind,
+        last_commit_ts=last_commit,
+        stale=bool(reasons),
+        stale_reasons=tuple(reasons),
+        error=error,
+    )
+
+
+def collect(  # noqa: PLR0913
+    repo: str,
+    *,
+    now: datetime,
+    stale_after_hours: int = DEFAULT_STALE_AFTER_HOURS,
+    activity: Mapping[str, datetime] | None = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    ahead_behind: bool = True,
+    max_workers: int = 6,
+) -> GitSnapshot:
+    """Snapshot every worktree of the repo containing ``repo``. Never raises.
+
+    ``activity`` maps ``worktree_id`` to the last observed hook activity, used only for the
+    ``inactive`` stale reason. ``now`` is injected for deterministic tests.
+    """
+    now = now.astimezone(UTC)
+    try:
+        common = git_common_dir(repo, timeout=timeout)
+    except NotAGitRepo as exc:
+        return _empty(now, f"not_a_git_repo: {exc}")
+    except GitUnavailable:
+        return _empty(now, "git_unavailable")
+    start = os.path.realpath(repo)
+    try:
+        listing = run_git(["worktree", "list", "--porcelain", "-z"], start, timeout=timeout)
+        nul = True
+        if listing is None or not listing.ok:
+            listing = run_git(["worktree", "list", "--porcelain"], start, timeout=timeout)
+            nul = False
+    except GitUnavailable:
+        return _empty(now, "git_unavailable", common)
+    if listing is None or not listing.ok:
+        return _empty(now, "worktree_list_failed", common)
+    entries = parse_porcelain(listing.text(), nul=nul)
+    stale_after = timedelta(hours=stale_after_hours)
+    activity = activity or {}
+
+    def probe(item: tuple[int, WorktreeEntry]) -> WorktreeSnapshot:
+        index, entry = item
+        real = os.path.realpath(entry.path) if os.path.isdir(entry.path) else None
+        wt_id = worktree_id_for(real) if real is not None else None
+        return _probe(
+            entry,
+            is_main=index == 0,
+            now=now,
+            stale_after=stale_after,
+            activity=activity.get(wt_id) if wt_id is not None else None,
+            timeout=timeout,
+            ahead_behind=ahead_behind,
+        )
+
+    if not entries:
+        return GitSnapshot(True, None, common, now, ())
+    with ThreadPoolExecutor(max_workers=max(1, min(max_workers, len(entries)))) as pool:
+        snapshots = list(pool.map(probe, enumerate(entries)))
+    snapshots.sort(key=lambda s: (not s.is_main, s.path))
+    return GitSnapshot(True, None, common, now, tuple(snapshots))