cortexshift 0.1.0__py3-none-any.whl

cortexshift/domain/__init__.py

@@ -0,0 +1,153 @@
+"""Core domain models for CortexShift."""
+
+from cortexshift.domain.checkpoint import (
+    CHECKPOINT_PROTOCOL_VERSION,
+    Checkpoint,
+    CheckpointGitState,
+    CheckpointKind,
+    CheckpointPayload,
+    CheckpointRecord,
+    CheckpointSourceSession,
+    CheckpointTaskSnapshot,
+    CheckpointTestProvenance,
+    CheckpointTestStatus,
+)
+from cortexshift.domain.doctor import (
+    AuthenticationStatus,
+    DoctorReport,
+    PlatformInfo,
+    ProviderDiagnostic,
+)
+from cortexshift.domain.errors import (
+    CheckpointNotFoundError,
+    CortexShiftError,
+    DatabaseStateError,
+    GitNotInstalledError,
+    GitProbeError,
+    GitProbeTimeoutError,
+    HandoffDeliveryError,
+    HandoffNotFoundError,
+    InvalidCheckpointInputError,
+    NoActiveTaskError,
+    NoSourceSessionError,
+    NotAGitRepositoryError,
+    ProjectAlreadyInitializedError,
+    ProjectConflictError,
+    ProjectNotInitializedError,
+    ProviderNotFoundError,
+    RepositoryInspectionError,
+    SameProviderSwitchError,
+    SessionNotFoundError,
+    SessionRecoveryError,
+    SessionTaskMismatchError,
+    SnapshotNotFoundError,
+    StateCorruptionError,
+    TaskAlreadyCompletedError,
+    TaskNotActivatableError,
+    TaskNotFoundError,
+    TerminalRequiredError,
+    UnknownProviderError,
+    UnsupportedPromptError,
+    UnsupportedSchemaVersionError,
+    WorkspaceLockedError,
+)
+from cortexshift.domain.git import GitSnapshot, RepositoryInspection, RepositoryInspectionStatus
+from cortexshift.domain.handoff import (
+    HANDOFF_PROTOCOL_VERSION,
+    HandoffFailureCode,
+    HandoffGitState,
+    HandoffPayload,
+    HandoffRecord,
+    HandoffSourceSession,
+    HandoffStatus,
+    HandoffTestStatus,
+)
+from cortexshift.domain.identifiers import generate_id, utc_now
+from cortexshift.domain.launch import LaunchSpecification
+from cortexshift.domain.project import Project
+from cortexshift.domain.provider import (
+    PROVIDER_ANTIGRAVITY,
+    PROVIDER_CLAUDE,
+    PROVIDER_CODEX,
+    ProviderCapabilities,
+    ProviderId,
+)
+from cortexshift.domain.session import Session, SessionExitReason, SessionStatus
+from cortexshift.domain.status import ActiveTaskSummary, ProgressSummary, ProjectStatus
+from cortexshift.domain.task import Task, TaskStatus
+
+__all__ = [
+    "ActiveTaskSummary",
+    "AuthenticationStatus",
+    "CHECKPOINT_PROTOCOL_VERSION",
+    "Checkpoint",
+    "CheckpointGitState",
+    "CheckpointKind",
+    "CheckpointNotFoundError",
+    "CheckpointPayload",
+    "CheckpointRecord",
+    "CheckpointSourceSession",
+    "CheckpointTaskSnapshot",
+    "CheckpointTestProvenance",
+    "CheckpointTestStatus",
+    "CortexShiftError",
+    "DatabaseStateError",
+    "DoctorReport",
+    "GitNotInstalledError",
+    "GitProbeError",
+    "GitProbeTimeoutError",
+    "GitSnapshot",
+    "HandoffDeliveryError",
+    "HandoffFailureCode",
+    "HandoffGitState",
+    "HandoffNotFoundError",
+    "HandoffPayload",
+    "HandoffRecord",
+    "HandoffSourceSession",
+    "HandoffStatus",
+    "HandoffTestStatus",
+    "InvalidCheckpointInputError",
+    "LaunchSpecification",
+    "NoActiveTaskError",
+    "NoSourceSessionError",
+    "NotAGitRepositoryError",
+    "PlatformInfo",
+    "ProgressSummary",
+    "Project",
+    "ProjectAlreadyInitializedError",
+    "ProjectConflictError",
+    "ProjectNotInitializedError",
+    "ProjectStatus",
+    "ProviderCapabilities",
+    "ProviderDiagnostic",
+    "ProviderId",
+    "ProviderNotFoundError",
+    "RepositoryInspection",
+    "RepositoryInspectionError",
+    "RepositoryInspectionStatus",
+    "SameProviderSwitchError",
+    "Session",
+    "SessionExitReason",
+    "SessionNotFoundError",
+    "SessionRecoveryError",
+    "SessionStatus",
+    "SessionTaskMismatchError",
+    "SnapshotNotFoundError",
+    "StateCorruptionError",
+    "Task",
+    "TaskAlreadyCompletedError",
+    "TaskNotActivatableError",
+    "TaskNotFoundError",
+    "TaskStatus",
+    "TerminalRequiredError",
+    "UnknownProviderError",
+    "UnsupportedPromptError",
+    "UnsupportedSchemaVersionError",
+    "WorkspaceLockedError",
+    "HANDOFF_PROTOCOL_VERSION",
+    "PROVIDER_ANTIGRAVITY",
+    "PROVIDER_CLAUDE",
+    "PROVIDER_CODEX",
+    "generate_id",
+    "utc_now",
+]

cortexshift/domain/checkpoint.py

@@ -0,0 +1,174 @@
+"""Domain models for the canonical CortexShift checkpoint protocol (Protocol v1).
+
+A Checkpoint is an immutable structured observation of the Task and repository at a
+meaningful point in development. Checkpoints do not contain provider transcripts,
+reasoning, full diffs, or file contents. They provide resilient, deterministic engineering
+evidence that enables recovery from crashes, quota exhaustion, and unexpected terminations
+without requiring the outgoing provider or model to still be available.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cortexshift.domain.git import RepositoryInspectionStatus
+from cortexshift.domain.identifiers import generate_id, utc_now
+from cortexshift.domain.provider import ProviderId
+from cortexshift.domain.session import SessionExitReason, SessionStatus
+
+CHECKPOINT_PROTOCOL_VERSION = 1
+
+MAX_OPERATOR_NOTE_CHARS = 2_000
+MAX_DECISION_CHARS = 1_000
+MAX_TEST_SUMMARY_CHARS = 1_000
+
+# Structured provenance marker recorded in the extensible `metadata` mapping that both
+# CheckpointRecord and CheckpointPayload already carry. ADR-0009 specifies that
+# `record_decision` persists its checkpoint with `trigger="decision"`; the marker lives in
+# existing free-form metadata, so Checkpoint Protocol v1 and SQLite schema v6 are unchanged.
+CHECKPOINT_TRIGGER_KEY = "trigger"
+CHECKPOINT_TRIGGER_DECISION = "decision"
+
+
+class CheckpointKind(StrEnum):
+    """Classification of how a checkpoint was captured.
+
+    - MANUAL: Explicitly requested by user or agent via `cortexshift checkpoint create`.
+    - SESSION_END: Automatically captured when a launched provider process terminates.
+    - RECOVERY: Reconstructed after an interrupted session via `cortexshift recover`.
+    """
+
+    MANUAL = "manual"
+    SESSION_END = "session_end"
+    RECOVERY = "recovery"
+
+
+class CheckpointTestProvenance(StrEnum):
+    """Origin and trustworthiness of recorded test status.
+
+    - UNKNOWN: No test execution was recorded or observed.
+    - REPORTED: Reported by human operator or agent, but not independently verified.
+    - VERIFIED: Directly observed and validated by a CortexShift verification subsystem.
+    """
+
+    UNKNOWN = "unknown"
+    REPORTED = "reported"
+    VERIFIED = "verified"
+
+
+class CheckpointTestStatus(BaseModel):
+    """Structured test status with explicit provenance.
+
+    A provider process exiting with code 0 does NOT prove tests passed. Where no
+    independently verified execution occurred, provenance remains REPORTED or UNKNOWN.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    known: bool = False
+    summary: str = "No independently verified test results recorded."
+    provenance: CheckpointTestProvenance = CheckpointTestProvenance.UNKNOWN
+
+
+class CheckpointTaskSnapshot(BaseModel):
+    """Historical point-in-time snapshot of the Task state.
+
+    Checkpoints preserve the Task state as it was when the checkpoint was captured,
+    ensuring historical immutability when the Task is later modified.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    task_id: str
+    task_title: str
+    task_status: str
+    objective: str
+    requirements: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+    completed: list[str] = Field(default_factory=list)
+    current_work: str | None = None
+    remaining: list[str] = Field(default_factory=list)
+    known_issues: list[str] = Field(default_factory=list)
+
+
+class CheckpointGitState(BaseModel):
+    """Historical point-in-time observation of Git state."""
+
+    model_config = ConfigDict(frozen=True)
+
+    status: RepositoryInspectionStatus
+    available: bool = False
+    note: str
+    branch: str | None = None
+    head_sha: str | None = None
+    detached_head: bool = False
+    dirty: bool = False
+    staged_count: int = 0
+    modified_count: int = 0
+    untracked_count: int = 0
+    conflicted_count: int = 0
+    working_tree_diff_summary: str | None = None
+    staged_diff_summary: str | None = None
+    snapshot_id: str | None = None
+
+
+class CheckpointSourceSession(BaseModel):
+    """Compact summary of the CortexShift Session associated with this checkpoint.
+
+    Provider transcripts, conversations, and reasoning are strictly excluded.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    session_id: str
+    provider_id: ProviderId
+    native_session_id: str | None = None
+    status: SessionStatus | None = None
+    exit_reason: SessionExitReason | None = None
+    exit_code: int | None = None
+
+
+class CheckpointPayload(BaseModel):
+    """Canonical structured point-in-time engineering context for a checkpoint."""
+
+    model_config = ConfigDict(frozen=True)
+
+    protocol_version: int = CHECKPOINT_PROTOCOL_VERSION
+    generated_at: datetime = Field(default_factory=utc_now)
+
+    task: CheckpointTaskSnapshot
+    git_state: CheckpointGitState
+    files_touched: list[str] = Field(default_factory=list)
+    decisions: list[str] = Field(default_factory=list)
+    test_status: CheckpointTestStatus = Field(default_factory=CheckpointTestStatus)
+    operator_note: str | None = None
+    source_session: CheckpointSourceSession | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+def generate_checkpoint_id() -> str:
+    """Generate default ID for checkpoints."""
+    return generate_id("cp")
+
+
+class CheckpointRecord(BaseModel):
+    """Canonical persistent checkpoint entity wrapping an immutable payload."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=generate_checkpoint_id)
+    protocol_version: int = CHECKPOINT_PROTOCOL_VERSION
+    project_id: str
+    task_id: str
+    session_id: str | None = None
+    git_snapshot_id: str | None = None
+    kind: CheckpointKind
+    payload: CheckpointPayload
+    created_at: datetime = Field(default_factory=utc_now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+# Canonical alias
+Checkpoint = CheckpointRecord

cortexshift/domain/doctor.py

@@ -0,0 +1,68 @@
+"""Domain models for environment inspection and provider diagnostics."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cortexshift.domain.provider import ProviderCapabilities, ProviderId
+
+
+class AuthenticationStatus(StrEnum):
+    """Status of provider CLI authentication."""
+
+    AUTHENTICATED = "authenticated"
+    NOT_AUTHENTICATED = "not_authenticated"
+    UNKNOWN = "unknown"
+    NOT_PROBED = "not_probed"
+
+
+class PlatformInfo(BaseModel):
+    """System and environment metadata for diagnostics."""
+
+    model_config = ConfigDict(frozen=True)
+
+    system: str
+    release: str
+    machine: str
+    python_version: str
+
+
+class ProviderDiagnostic(BaseModel):
+    """Diagnostic health and capability record for a single provider CLI."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: ProviderId
+    display_name: str
+    executable: str
+    installed: bool
+    resolved_path: str | None = None
+    version: str | None = None
+    authentication_status: AuthenticationStatus = AuthenticationStatus.UNKNOWN
+    capabilities: ProviderCapabilities
+    diagnostics: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def id(self) -> ProviderId:
+        """Alias for provider_id for serialization convenience."""
+        return self.provider_id
+
+    @property
+    def authentication(self) -> AuthenticationStatus:
+        """Alias for authentication_status."""
+        return self.authentication_status
+
+
+class DoctorReport(BaseModel):
+    """Aggregate diagnostic report generated by `cortexshift doctor`."""
+
+    model_config = ConfigDict(frozen=True)
+
+    cortexshift_version: str
+    python_version: str
+    platform: PlatformInfo
+    timestamp: datetime
+    providers: list[ProviderDiagnostic]

cortexshift/domain/errors.py

@@ -0,0 +1,277 @@
+"""Domain and application exception hierarchy for CortexShift."""
+
+from pathlib import Path
+
+
+class CortexShiftError(Exception):
+    """Base exception for all CortexShift domain and application errors."""
+
+
+class NativeResumeError(CortexShiftError):
+    """An exact native resume cannot be performed safely."""
+
+
+class ProjectNotInitializedError(CortexShiftError):
+    """Raised when an operation requires an initialized CortexShift project but none was found."""
+
+    def __init__(self, message: str = "CortexShift is not initialized here.") -> None:
+        super().__init__(message)
+
+
+class ProjectAlreadyInitializedError(CortexShiftError):
+    """Raised when initialization is attempted on an already initialized project."""
+
+    def __init__(self, project_name: str, path: str) -> None:
+        super().__init__(f"CortexShift is already initialized for {project_name} at {path}.")
+        self.project_name = project_name
+        self.path = path
+
+
+class ProjectConflictError(CortexShiftError):
+    """Raised when existing project state conflicts with the target directory."""
+
+
+class TaskNotFoundError(CortexShiftError):
+    """Raised when a task with the specified identifier cannot be found."""
+
+    def __init__(self, task_id: str) -> None:
+        super().__init__(f"Task '{task_id}' was not found.")
+        self.task_id = task_id
+
+
+class NoActiveTaskError(CortexShiftError):
+    """Raised when an active task operation is requested but no task is currently active."""
+
+    def __init__(self, message: str = "No active task found for this project.") -> None:
+        super().__init__(message)
+
+
+class TaskNotActivatableError(CortexShiftError):
+    """Raised when attempting to activate a task in an ineligible or terminal state."""
+
+
+class TaskAlreadyCompletedError(CortexShiftError):
+    """Raised when attempting to complete a task that is already completed."""
+
+    def __init__(self, task_id: str) -> None:
+        super().__init__(f"Task '{task_id}' is already completed.")
+        self.task_id = task_id
+
+
+class DatabaseStateError(CortexShiftError):
+    """Base exception for persistent storage failures."""
+
+
+class UnsupportedSchemaVersionError(DatabaseStateError):
+    """Raised when database schema version is newer than supported by this CortexShift version."""
+
+    def __init__(self, current_version: int, max_supported_version: int) -> None:
+        super().__init__(
+            f"This CortexShift state was created by a newer incompatible version "
+            f"(schema v{current_version}, supported up to v{max_supported_version})."
+        )
+        self.current_version = current_version
+        self.max_supported_version = max_supported_version
+
+
+class StateCorruptionError(DatabaseStateError):
+    """Raised when database state is corrupted, malformed, or unreadable."""
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(f"CortexShift state could not be opened: {detail}")
+        self.detail = detail
+
+
+class RepositoryInspectionError(CortexShiftError):
+    """Base exception for repository inspection failures."""
+
+
+class GitNotInstalledError(RepositoryInspectionError):
+    """Raised when Git is required but not installed or found in PATH."""
+
+    def __init__(self, message: str = "Git executable was not found in PATH.") -> None:
+        super().__init__(message)
+
+
+class NotAGitRepositoryError(RepositoryInspectionError):
+    """Raised when the project is not inside a Git repository."""
+
+    def __init__(
+        self,
+        message: str = "This CortexShift project is not inside a Git repository.",
+    ) -> None:
+        super().__init__(message)
+
+
+class GitProbeTimeoutError(RepositoryInspectionError):
+    """Raised when a Git command times out during inspection."""
+
+    def __init__(self, message: str = "Git inspection timed out.") -> None:
+        super().__init__(message)
+
+
+class GitProbeError(RepositoryInspectionError):
+    """Raised when a Git inspection command fails unexpectedly."""
+
+    def __init__(self, message: str = "Git repository inspection failed.") -> None:
+        super().__init__(message)
+
+
+class SnapshotNotFoundError(CortexShiftError):
+    """Raised when a repository snapshot with the specified identifier cannot be found."""
+
+    def __init__(self, snapshot_id: str) -> None:
+        super().__init__(f"Snapshot '{snapshot_id}' was not found.")
+        self.snapshot_id = snapshot_id
+
+
+class ProviderNotFoundError(CortexShiftError):
+    """Raised when a requested provider executable is not found in PATH."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class UnknownProviderError(CortexShiftError, ValueError):
+    """Raised when an unrecognized provider ID is requested."""
+
+    def __init__(self, provider_id: str, supported: list[str]) -> None:
+        self.provider_id = provider_id
+        self.supported = supported
+        super().__init__(
+            f"Unknown provider '{provider_id}'. Supported providers: {', '.join(supported)}"
+        )
+
+
+class UnsupportedPromptError(CortexShiftError):
+    """Raised when an initial prompt is provided to a provider that does not support it."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class WorkspaceLockedError(CortexShiftError):
+    """Raised when an exclusive workspace lease cannot be acquired."""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        lock_path: Path | None = None,
+    ) -> None:
+        self.lock_path = lock_path
+        if message is None:
+            message = (
+                "Another CortexShift agent session is already active for this project.\n\n"
+                "Lock file: .cortexshift/agent.lock\n\n"
+                "Wait for that session to finish and try again."
+            )
+        super().__init__(message)
+
+
+class TerminalRequiredError(CortexShiftError):
+    """Raised when an interactive provider session is attempted without a usable TTY."""
+
+    def __init__(
+        self,
+        message: str = (
+            "Interactive provider launch requires a terminal (TTY).\n\n"
+            "To simulate provider launch non-interactively, use: "
+            "cortexshift run <provider> --dry-run"
+        ),
+    ) -> None:
+        super().__init__(message)
+
+
+class SessionNotFoundError(CortexShiftError):
+    """Raised when a session with the specified identifier cannot be found."""
+
+    def __init__(self, session_id: str) -> None:
+        super().__init__(f"Session '{session_id}' was not found.")
+        self.session_id = session_id
+
+
+class NoSourceSessionError(CortexShiftError):
+    """Raised when a handoff is requested but no prior CortexShift Session exists.
+
+    `switch` is strictly a provider handoff operation; it never silently degrades into
+    a first-agent `run`.
+    """
+
+    def __init__(self, message: str | None = None) -> None:
+        if message is None:
+            message = (
+                "No previous CortexShift session exists for the active task.\n\n"
+                "There is nothing to hand off yet.\n\n"
+                "Start the first agent on this task with:\n\n"
+                "  cortexshift run <provider>\n"
+            )
+        super().__init__(message)
+
+
+class SessionTaskMismatchError(CortexShiftError):
+    """Raised when an explicitly selected source Session does not belong to the active task."""
+
+    def __init__(self, session_id: str, task_id: str) -> None:
+        super().__init__(
+            f"Session '{session_id}' does not belong to the active task '{task_id}'.\n\n"
+            "A handoff source session must belong to the currently active CortexShift task."
+        )
+        self.session_id = session_id
+        self.task_id = task_id
+
+
+class SameProviderSwitchError(CortexShiftError):
+    """Raised when the handoff target provider equals the source session provider."""
+
+    def __init__(self, provider_display_name: str) -> None:
+        super().__init__(
+            f"The latest task session already uses {provider_display_name}.\n\n"
+            "CortexShift switch is intended for provider handoff.\n\n"
+            "Choose a different target provider, or select an explicit source session "
+            "with --from-session."
+        )
+        self.provider_display_name = provider_display_name
+
+
+class HandoffNotFoundError(CortexShiftError):
+    """Raised when a handoff with the specified identifier cannot be found."""
+
+    def __init__(self, handoff_id: str) -> None:
+        super().__init__(f"Handoff '{handoff_id}' was not found.")
+        self.handoff_id = handoff_id
+
+
+class HandoffDeliveryError(CortexShiftError):
+    """Raised when handoff context could not be delivered to the target provider.
+
+    Carries a safe machine classification. Raw provider stdout/stderr and any provider
+    bootstrap response are deliberately excluded from both the message and the code.
+    """
+
+    def __init__(self, failure_code: str, message: str) -> None:
+        super().__init__(message)
+        self.failure_code = failure_code
+
+
+class CheckpointNotFoundError(CortexShiftError):
+    """Raised when a checkpoint with the specified identifier cannot be found."""
+
+    def __init__(self, checkpoint_id: str) -> None:
+        super().__init__(f"Checkpoint '{checkpoint_id}' was not found.")
+        self.checkpoint_id = checkpoint_id
+
+
+class InvalidCheckpointInputError(CortexShiftError):
+    """Raised when user or agent checkpoint input exceeds bounds or fails validation."""
+
+
+class SessionRecoveryError(CortexShiftError):
+    """Raised when crash recovery encounters an unrecoverable orchestration condition."""
+
+
+class McpContextError(CortexShiftError):
+    """Raised when MCP execution context resolution or validation fails."""
+
+
+class McpReadOnlyError(CortexShiftError):
+    """Raised when a state-mutating MCP tool is invoked in read-only or unmanaged mode."""