cursorfleet 0.1.0__py3-none-any.whl

cursorfleet/config/models.py

@@ -0,0 +1,154 @@
+"""Model of ``.cursorfleet/config.toml`` (schema_version "1.0"); source of config.schema.json.
+
+Config is data, never code: nothing in it is executed. There is intentionally no
+setting that stores prompts, thinking, responses, file contents or command
+output, and none that enables a network call or a forbidden hook.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, field_validator
+
+from cursorfleet.events.kinds import COMMAND_DISPLAY_MAX_CHARS
+from cursorfleet.events.pathcheck import check_not_in_git_dir, check_relative_posix
+
+# Must equal ALLOWED_V01_HOOKS (asserted by a unit test). Forbidden hooks are
+# not representable, so a config file can never ask the installer to emit them.
+HookName = Literal[
+    "sessionStart",
+    "sessionEnd",
+    "preToolUse",
+    "postToolUse",
+    "postToolUseFailure",
+    "subagentStart",
+    "subagentStop",
+    "beforeShellExecution",
+    "afterShellExecution",
+    "afterFileEdit",
+    "preCompact",
+    "stop",
+]
+
+_DEFAULT_HOOKS: tuple[HookName, ...] = (
+    "sessionStart",
+    "sessionEnd",
+    "preToolUse",
+    "postToolUse",
+    "postToolUseFailure",
+    "subagentStart",
+    "subagentStop",
+    "beforeShellExecution",
+    "afterShellExecution",
+    "afterFileEdit",
+    "preCompact",
+    "stop",
+)
+
+_STRICT = ConfigDict(extra="forbid", frozen=True)
+_VersionStr = Annotated[str, Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._+\-]{0,63}$")]
+
+
+def _relative(value: str) -> str:
+    return check_not_in_git_dir(check_relative_posix(value))
+
+
+class RetentionConfig(BaseModel):
+    """Spool retention. Defaults: 14 days or 50 MB per session, whichever comes first."""
+
+    model_config = _STRICT
+
+    max_age_days: int = Field(default=14, ge=1, le=365)
+    max_session_mb: int = Field(default=50, ge=1, le=1024)
+
+
+class PrivacyConfig(BaseModel):
+    """Knobs can only reduce what is stored; they cannot add content fields."""
+
+    model_config = _STRICT
+
+    store_command_display: bool = False
+    command_display_max_chars: int = Field(default=COMMAND_DISPLAY_MAX_CHARS, ge=20, le=200)
+    hash_commands: bool = True
+
+
+class HooksConfig(BaseModel):
+    """Which passive hooks the installer registers (subset of the 12 allowed)."""
+
+    model_config = _STRICT
+
+    enabled: tuple[HookName, ...] = _DEFAULT_HOOKS
+
+    @field_validator("enabled")
+    @classmethod
+    def _unique(cls, value: tuple[HookName, ...]) -> tuple[HookName, ...]:
+        if len(set(value)) != len(value):
+            msg = "hooks.enabled must not contain duplicates"
+            raise ValueError(msg)
+        return value
+
+
+class GitConfig(BaseModel):
+    """Read-only git/worktree collector settings."""
+
+    model_config = _STRICT
+
+    refresh_interval_s: int = Field(default=5, ge=1, le=3600)
+    stale_after_hours: int = Field(default=72, ge=1, le=24 * 365)
+    ahead_behind: bool = True
+
+
+class TuiConfig(BaseModel):
+    model_config = _STRICT
+
+    refresh_interval_ms: int = Field(default=500, ge=100, le=10_000)
+
+
+class CursorConfig(BaseModel):
+    """Cursor-specific settings."""
+
+    model_config = _STRICT
+
+    validated_versions: tuple[_VersionStr, ...] = Field(
+        default=(),
+        description="Cursor versions you have verified; `doctor` warns on others. "
+        "Empty until a live capture has been reviewed (ADR 0001).",
+    )
+
+
+class WorkConfig(BaseModel):
+    model_config = _STRICT
+
+    dir: Annotated[str, AfterValidator(_relative)] = Field(
+        default=".cursorfleet/work",
+        description="Workspace-relative directory holding agent-declared Markdown artifacts.",
+    )
+
+
+class FleetConfig(BaseModel):
+    """Root of ``.cursorfleet/config.toml``."""
+
+    model_config = _STRICT
+
+    schema_version: Literal["1.0"] = "1.0"
+    retention: RetentionConfig = Field(default_factory=RetentionConfig)
+    privacy: PrivacyConfig = Field(default_factory=PrivacyConfig)
+    hooks: HooksConfig = Field(default_factory=HooksConfig)
+    git: GitConfig = Field(default_factory=GitConfig)
+    tui: TuiConfig = Field(default_factory=TuiConfig)
+    cursor: CursorConfig = Field(default_factory=CursorConfig)
+    work: WorkConfig = Field(default_factory=WorkConfig)
+
+
+__all__ = [
+    "CursorConfig",
+    "FleetConfig",
+    "GitConfig",
+    "HookName",
+    "HooksConfig",
+    "PrivacyConfig",
+    "RetentionConfig",
+    "TuiConfig",
+    "WorkConfig",
+]

cursorfleet/config/roster.py

@@ -0,0 +1,245 @@
+"""Model of ``.cursorfleet/roster.toml`` (schema_version "1.0") and the default roster.
+
+The roster is the source of truth. Generators (M1) render ``.cursor/agents/*.md``,
+rules and skills from it; roster semantics are never stored only in Markdown.
+
+Cursor subagent frontmatter supports only name, description, model, readonly and
+is_background (ADR 0001, A7). Everything under ``capability_notes`` is
+DOCUMENTATION ONLY: Cursor cannot enforce per-agent tools, paths, network or git
+capability, and v0.1 does not either.
+
+PROVISIONAL (ADR 0001 Q2): how a custom subagent name appears in
+``subagent_type``. ``Roster.role_for_subagent_type`` degrades to ``None`` for
+anything unrecognised so callers fall back to the raw value.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+_STRICT = ConfigDict(extra="forbid", frozen=True)
+
+RosterId = Annotated[str, Field(pattern=r"^[a-z][a-z0-9\-]{1,39}$")]
+Model = Annotated[str, Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._:/\[\]=,\- ]{0,127}$")]
+Note = Annotated[str, Field(min_length=1, max_length=200)]
+
+
+class Role(StrEnum):
+    """Workflow function. Several agents may share one role (alpha/beta implementers)."""
+
+    COORDINATOR = "coordinator"
+    ARCHITECT = "architect"
+    SCOUT = "scout"
+    IMPLEMENTER = "implementer"
+    TESTER = "tester"
+    REVIEWER = "reviewer"
+    PATCHER = "patcher"
+    QA = "qa"
+
+
+class AgentSpec(BaseModel):
+    """A Cursor subagent rendered to ``.cursor/agents/<name>.md``."""
+
+    model_config = _STRICT
+
+    id: RosterId = Field(description="Stable slug; also the value stored in event.agent_role.")
+    role: Role
+    description: str = Field(
+        min_length=20,
+        max_length=1024,
+        description="Delegation hint Cursor reads; keep it sharp (when to use, when not to).",
+    )
+    readonly: bool = Field(description="Cursor's only permission-like switch; coarse.")
+    model: Model = "inherit"
+    is_background: bool = False
+    enabled: bool = True
+    capability_notes: tuple[Note, ...] = Field(
+        default=(),
+        max_length=10,
+        description="DOCUMENTATION ONLY. Not enforced by Cursor or by CursorFleet v0.1.",
+    )
+
+    @model_validator(mode="after")
+    def _not_coordinator(self) -> Self:
+        if self.role is Role.COORDINATOR:
+            msg = "the coordinator is the main agent, not a subagent; use roster.coordinator"
+            raise ValueError(msg)
+        return self
+
+
+class CoordinatorSpec(BaseModel):
+    """The main agent, driven by a skill and/or rule. Never rendered as a subagent file.
+
+    Design choice (ADR 0001 A7), not a platform limit.
+    """
+
+    model_config = _STRICT
+
+    id: Literal["coordinator"] = "coordinator"
+    role: Literal[Role.COORDINATOR] = Role.COORDINATOR
+    description: str = Field(min_length=20, max_length=1024)
+    delivery: Literal["skill", "rule", "both"] = "skill"
+    enabled: bool = True
+    capability_notes: tuple[Note, ...] = Field(default=(), max_length=10)
+
+
+class Roster(BaseModel):
+    """Root of ``.cursorfleet/roster.toml``."""
+
+    model_config = _STRICT
+
+    schema_version: Literal["1.0"] = "1.0"
+    name_prefix: Annotated[str, Field(pattern=r"^([a-z][a-z0-9]{0,15}-)?$")] = Field(
+        default="cf-",
+        description="Prefix for generated Cursor subagent names. PROVISIONAL (ADR 0001 Q2).",
+    )
+    coordinator: CoordinatorSpec
+    agents: tuple[AgentSpec, ...] = Field(min_length=1, max_length=32)
+
+    @model_validator(mode="after")
+    def _unique_ids(self) -> Self:
+        ids = [self.coordinator.id, *(a.id for a in self.agents)]
+        if len(set(ids)) != len(ids):
+            msg = "roster ids must be unique and must not reuse 'coordinator'"
+            raise ValueError(msg)
+        return self
+
+    def enabled_agents(self) -> tuple[AgentSpec, ...]:
+        return tuple(a for a in self.agents if a.enabled)
+
+    def cursor_name(self, agent_id: str) -> str:
+        """Subagent name written to ``.cursor/agents`` frontmatter and filename."""
+        return f"{self.name_prefix}{agent_id}"
+
+    def role_for_subagent_type(self, subagent_type: str) -> str | None:
+        """Map a hook ``subagent_type`` to a roster id, or ``None`` if unrecognised.
+
+        Accepts the prefixed Cursor name or the bare id. Built-ins such as
+        ``generalPurpose`` and ``explore`` return ``None``; callers then keep the
+        raw value as ``agent_role``.
+        """
+        bare = subagent_type.removeprefix(self.name_prefix) if self.name_prefix else subagent_type
+        for agent in self.agents:
+            if bare == agent.id:
+                return agent.id
+        return None
+
+
+def default_roster() -> Roster:
+    """Default roster: the coordinator plus 7 enabled subagents; implementer-beta is off."""
+    return Roster(
+        coordinator=CoordinatorSpec(
+            description=(
+                "Main-agent playbook: split work, delegate to roster subagents, track handoffs "
+                "and blockers in .cursorfleet/work/, and never declare done on its own."
+            ),
+            capability_notes=(
+                "Runs as the main agent via a skill; it is not a subagent file.",
+                "Asks for isolated worktrees in the prompt when parallel implementers are used.",
+            ),
+        ),
+        agents=(
+            AgentSpec(
+                id="architect",
+                role=Role.ARCHITECT,
+                description=(
+                    "Use for design and planning before code changes: module boundaries, "
+                    "interfaces, trade-offs, a written plan. Do not use for implementation."
+                ),
+                readonly=True,
+                capability_notes=("Intended to read the repo and write plan artifacts only.",),
+            ),
+            AgentSpec(
+                id="repo-scout",
+                role=Role.SCOUT,
+                description=(
+                    "Use to map unfamiliar code: find files, trace call paths, summarize "
+                    "conventions. Read-only exploration; do not use to change code."
+                ),
+                readonly=True,
+                capability_notes=("Intended to be read-only; cheap model is acceptable.",),
+            ),
+            AgentSpec(
+                id="implementer-alpha",
+                role=Role.IMPLEMENTER,
+                description=(
+                    "Use to implement a scoped, already-planned change in the working tree and "
+                    "report a handoff. Do not use for design or for reviewing its own work."
+                ),
+                readonly=False,
+                capability_notes=(
+                    "Intended write scope: files named in the plan.",
+                    "Ask for an isolated worktree when running beside another implementer.",
+                ),
+            ),
+            AgentSpec(
+                id="test-engineer",
+                role=Role.TESTER,
+                description=(
+                    "Use to write and run tests for a change and report results. "
+                    "Do not use to change production code beyond testability hooks."
+                ),
+                readonly=False,
+                capability_notes=("Intended write scope: test directories and fixtures.",),
+            ),
+            AgentSpec(
+                id="reviewer",
+                role=Role.REVIEWER,
+                description=(
+                    "Use for independent review of a diff: correctness, security, privacy, "
+                    "conventions. Read-only; never fixes issues itself, hands them to the patcher."
+                ),
+                readonly=True,
+                capability_notes=(
+                    "Pin a different model family than the implementer for independence; "
+                    "Cursor may silently fall back to a compatible model.",
+                ),
+            ),
+            AgentSpec(
+                id="patch-engineer",
+                role=Role.PATCHER,
+                description=(
+                    "Use to apply review findings with minimal, targeted fixes and re-report. "
+                    "Do not use for new features or refactors."
+                ),
+                readonly=False,
+                capability_notes=("Intended write scope: files cited in review findings.",),
+            ),
+            AgentSpec(
+                id="qa-release",
+                role=Role.QA,
+                description=(
+                    "Use to verify a finished change: clean install, lint, types, tests, build, "
+                    "release notes. Reports evidence; does not edit source."
+                ),
+                readonly=False,
+                capability_notes=(
+                    "Needs shell access (so not readonly) but is intended not to edit source.",
+                    "Cursor has no clean-environment primitive; v0.1 cannot guarantee one.",
+                ),
+            ),
+            AgentSpec(
+                id="implementer-beta",
+                role=Role.IMPLEMENTER,
+                description=(
+                    "Optional second implementer for parallel work in its own worktree. "
+                    "Disabled by default; enable only when tasks are truly independent."
+                ),
+                readonly=False,
+                enabled=False,
+                capability_notes=("Parallel work without isolation can overwrite alpha's edits.",),
+            ),
+        ),
+    )
+
+
+__all__ = [
+    "AgentSpec",
+    "CoordinatorSpec",
+    "Role",
+    "Roster",
+    "default_roster",
+]

cursorfleet/events/__init__.py

@@ -0,0 +1,39 @@
+"""Normalized event model for CursorFleet.
+
+Importing this package is cheap and stdlib-only. Pydantic models live in
+``cursorfleet.events.models`` and are re-exported lazily (PEP 562) so the hook
+hot path can import ``cursorfleet.events.kinds``/``ids``/``forbidden`` without
+pulling in pydantic.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+TYPE_CHECKING = False  # not ``typing.TYPE_CHECKING``: importing typing costs ~2 ms per hook
+if TYPE_CHECKING:
+    from cursorfleet.events.models import (
+        Event,
+        GateRef,
+        Metrics,
+        SanitizedCommand,
+        SanitizedPath,
+    )
+
+_LAZY = {
+    "Event": "cursorfleet.events.models",
+    "GateRef": "cursorfleet.events.models",
+    "Metrics": "cursorfleet.events.models",
+    "SanitizedCommand": "cursorfleet.events.models",
+    "SanitizedPath": "cursorfleet.events.models",
+}
+
+__all__ = ["Event", "GateRef", "Metrics", "SanitizedCommand", "SanitizedPath"]
+
+
+def __getattr__(name: str) -> object:
+    module = _LAZY.get(name)
+    if module is None:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+    return getattr(import_module(module), name)

cursorfleet/events/forbidden.py

@@ -0,0 +1,45 @@
+"""Field names that must never appear in a persisted event. Stdlib only.
+
+These are Cursor payload fields (or obvious aliases) carrying prompts,
+thinking, responses, file contents, command output, environment, emails or
+transcript locations. The event models reject every one of them (extra="forbid"),
+and security tests assert none is a model field.
+"""
+
+from __future__ import annotations
+
+FORBIDDEN_EVENT_FIELD_NAMES: frozenset[str] = frozenset(
+    {
+        "prompt",
+        "thought",
+        "thinking",
+        "response",
+        "text",
+        "message",
+        "content",
+        "contents",
+        "file_content",
+        "file_contents",
+        "output",
+        "stdout",
+        "stderr",
+        "tool_input",
+        "tool_output",
+        "error_message",
+        "edits",
+        "task",
+        "summary",
+        "description",
+        "attachments",
+        "env",
+        "environment",
+        "user_email",
+        "email",
+        "transcript_path",
+        "agent_transcript_path",
+        "workspace_roots",
+        "cwd",
+        "file_path",
+        "modified_files",
+    }
+)

cursorfleet/events/ids.py

@@ -0,0 +1,109 @@
+"""Stdlib-only identifier helpers (hot-path safe)."""
+
+from __future__ import annotations
+
+import os
+import time
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+# Single source for the ULID shape; the Pydantic models and tests reuse it.
+ULID_PATTERN = r"^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
+SAFE_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._:\-]{0,127}$"
+AGENT_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._:\-]{0,127}(#[A-Za-z0-9][A-Za-z0-9._:\-]{0,127})?$"
+
+
+def _encode(value: int, length: int) -> str:
+    chars = []
+    for _ in range(length):
+        chars.append(_CROCKFORD[value & 31])
+        value >>= 5
+    return "".join(reversed(chars))
+
+
+def new_event_id(now_ms: int | None = None, entropy: bytes | None = None) -> str:
+    """Return a 26-char ULID-style id: 48-bit ms timestamp + 80 random bits.
+
+    Lexicographic order follows time at millisecond resolution. Ids created in
+    the same millisecond are not guaranteed to be ordered.
+    """
+    ms = time.time_ns() // 1_000_000 if now_ms is None else now_ms
+    if not 0 <= ms < 1 << 48:
+        msg = "timestamp out of 48-bit range"
+        raise ValueError(msg)
+    raw = os.urandom(10) if entropy is None else entropy
+    if len(raw) != 10:
+        msg = "entropy must be exactly 10 bytes"
+        raise ValueError(msg)
+    return _encode(ms, 10) + _encode(int.from_bytes(raw, "big"), 16)
+
+
+def derive_agent_id(agent_role: str | None, agent_instance_id: str | None) -> str | None:
+    """Derive ``agent_id``: ``role#instance``; ``None`` when nothing identifies the agent.
+
+    ``#`` is outside the SafeId alphabet, so the result is unambiguous. ``None``
+    means "main agent or unattributed" (ADR 0003, PROVISIONAL until Q1 is answered).
+    """
+    if agent_role is None and agent_instance_id is None:
+        return None
+    if agent_instance_id is None:
+        return agent_role
+    return f"{agent_role or 'unknown'}#{agent_instance_id}"
+
+
+_SAFE_ID_RE_SRC = SAFE_ID_PATTERN
+_FS_SAFE_RE_SRC = r"^[A-Za-z0-9][A-Za-z0-9._\-]{0,127}$"
+_WINDOWS_RESERVED = frozenset(
+    {"con", "prn", "aux", "nul"}
+    | {f"com{i}" for i in range(1, 10)}
+    | {f"lpt{i}" for i in range(1, 10)}
+)
+
+
+def _sha256_hex(data: bytes) -> str:
+    import hashlib  # lazy: hashlib costs ~2 ms of import time on the hot path
+
+    return hashlib.sha256(data).hexdigest()
+
+
+def worktree_id_for(top_level_realpath: str) -> str:
+    """``wt-`` + first 12 hex of SHA-256 of the (normcased) realpath of a worktree top level.
+
+    Callers must pass ``os.path.realpath(...)`` output. ``normcase`` makes the id stable
+    on case-insensitive Windows paths; it is the identity function on POSIX.
+    """
+    norm = os.path.normcase(top_level_realpath)
+    return "wt-" + _sha256_hex(norm.encode("utf-8", "surrogateescape"))[:12]
+
+
+def safe_id(value: object, *, max_len: int = 128) -> str | None:
+    """Return ``value`` if it is a valid SafeId, else a stable ``h-<24 hex>`` hash, else None.
+
+    Non-strings, empty strings and absurdly long strings yield ``None`` (never raise).
+    """
+    import re
+
+    if not isinstance(value, str) or not value or len(value) > 4096:
+        return None
+    if len(value) <= max_len and re.match(_SAFE_ID_RE_SRC, value):
+        return value
+    return "h-" + _sha256_hex(value.encode("utf-8", "surrogateescape"))[:24]
+
+
+def fs_name_for(identifier: str) -> str:
+    """Directory/file stem for an id: Windows-, macOS- and Linux-safe, never traversing.
+
+    Ids that are not already portable (``:`` is illegal on Windows, reserved device
+    names, trailing dots, upper case, over-long) are replaced by a stable ``h-<24 hex>`` hash.
+    """
+    import re
+
+    if (
+        re.match(_FS_SAFE_RE_SRC, identifier)
+        and not identifier.endswith(".")
+        and identifier.split(".", 1)[0].lower() not in _WINDOWS_RESERVED
+        and not identifier.startswith("h-")  # keep the hash namespace collision-free
+        and identifier == identifier.lower()  # case-insensitive filesystems (macOS, Windows)
+    ):
+        return identifier
+    return "h-" + _sha256_hex(identifier.encode("utf-8", "surrogateescape"))[:24]