cortexshift 0.1.0__py3-none-any.whl

cortexshift/domain/git.py

@@ -0,0 +1,102 @@
+"""Domain model for Git repository snapshots and inspection results."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from cortexshift.domain.identifiers import generate_id, utc_now
+
+
+class RepositoryInspectionStatus(StrEnum):
+    """Status classification of a repository inspection."""
+
+    READY = "ready"
+    GIT_NOT_INSTALLED = "git_not_installed"
+    NOT_GIT_REPOSITORY = "not_git_repository"
+    PROBE_ERROR = "probe_error"
+
+
+class GitSnapshot(BaseModel):
+    """Snapshot of a repository's Git working tree and commit state.
+
+    Represents an immutable, empirical version control observation at capture time.
+    A stored snapshot is evidence of what was true when captured, never proof of
+    current working tree reality after modifications occur.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=lambda: generate_id("snap"))
+    project_id: str
+    project_root: str
+    git_root: str
+    git_version: str | None = None
+    branch: str | None = None
+    head_sha: str | None = None
+    detached_head: bool = False
+    dirty: bool = False
+    staged_files: list[str] = Field(default_factory=list)
+    modified_files: list[str] = Field(default_factory=list)
+    untracked_files: list[str] = Field(default_factory=list)
+    conflicted_files: list[str] = Field(default_factory=list)
+    working_tree_diff_summary: str | None = None
+    staged_diff_summary: str | None = None
+    captured_at: datetime = Field(default_factory=utc_now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _migrate_legacy_inputs(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            if "repo_path" in data:
+                data.setdefault("project_root", data["repo_path"])
+                data.setdefault("git_root", data["repo_path"])
+            if "is_dirty" in data:
+                data.setdefault("dirty", data["is_dirty"])
+            if "snapshot_at" in data:
+                data.setdefault("captured_at", data["snapshot_at"])
+            if "diff_summary" in data:
+                data.setdefault("working_tree_diff_summary", data["diff_summary"])
+            data.setdefault("project_id", "proj_default")
+        return data
+
+    @property
+    def repo_path(self) -> str:
+        """Backward-compatible alias for project_root."""
+        return self.project_root
+
+    @property
+    def is_dirty(self) -> bool:
+        """Backward-compatible alias for dirty."""
+        return self.dirty
+
+    @property
+    def snapshot_at(self) -> datetime:
+        """Backward-compatible alias for captured_at."""
+        return self.captured_at
+
+    @property
+    def diff_summary(self) -> str | None:
+        """Backward-compatible alias for working_tree_diff_summary."""
+        return self.working_tree_diff_summary
+
+
+class RepositoryInspection(BaseModel):
+    """Result of a live repository inspection."""
+
+    model_config = ConfigDict(frozen=True)
+
+    status: RepositoryInspectionStatus
+    project_root: str
+    git_available: bool
+    git_version: str | None = None
+    snapshot: GitSnapshot | None = None
+    diagnostic: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def is_ready(self) -> bool:
+        """Return True if the repository was successfully inspected and ready."""
+        return self.status == RepositoryInspectionStatus.READY and self.snapshot is not None

cortexshift/domain/handoff.py

@@ -0,0 +1,241 @@
+"""Domain models for the canonical, provider-independent CortexShift handoff protocol.
+
+A handoff is an immutable point-in-time context package that allows a CortexShift Task
+to move from one coding agent to another without requiring the outgoing agent to still
+be available. Two concepts are modelled explicitly:
+
+- ``HandoffPayload``: the canonical point-in-time engineering context (protocol v1).
+- ``HandoffRecord``: orchestration and delivery metadata wrapping a payload.
+
+The payload is deliberately provider-neutral. Provider-specific transport (how the
+context reaches a given CLI) lives behind handoff delivery adapters, and rendered
+provider prompts are never persisted.
+"""
+
+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
+
+# Version of the canonical handoff contract. Deliberately independent from the
+# SQLite schema version: handoff formatting and canonical fields may evolve
+# without a database migration, and vice versa.
+HANDOFF_PROTOCOL_VERSION = 1
+
+# Maximum number of characters retained for an operator-supplied note. The note is
+# optional advisory context and must never make the canonical payload unbounded.
+MAX_OPERATOR_NOTE_CHARS = 2_000
+
+
+class HandoffStatus(StrEnum):
+    """Delivery lifecycle of a handoff record.
+
+    - PREPARED: canonical handoff exists; target delivery is not yet known complete.
+    - DELIVERED: handoff context was successfully delivered via the provider strategy.
+    - FAILED: delivery or provider bootstrap could not be completed.
+
+    Handoff status is distinct from Session status: the target Session remains the
+    source of truth for how the receiving coding session itself eventually ended.
+    """
+
+    PREPARED = "prepared"
+    DELIVERED = "delivered"
+    FAILED = "failed"
+
+
+class HandoffFailureCode(StrEnum):
+    """Safe machine classification of a handoff delivery failure.
+
+    Failure codes never embed raw provider stdout/stderr, credentials, or prompts.
+    """
+
+    TARGET_PROVIDER_MISSING = "target_provider_missing"
+    BOOTSTRAP_FAILED = "bootstrap_failed"
+    BOOTSTRAP_TIMEOUT = "bootstrap_timeout"
+    BOOTSTRAP_INVALID_OUTPUT = "bootstrap_invalid_output"
+    SPAWN_FAILED = "spawn_failed"
+    WORKSPACE_LOCKED = "workspace_locked"
+
+
+class HandoffGitState(BaseModel):
+    """Canonical Git-state section of a handoff payload.
+
+    CortexShift projects do not require Git. When Git is unavailable or the project is
+    not a repository, this records an explicit, honest marker rather than fabricating
+    repository facts. When Git is ready, ``snapshot_id`` references the immutable
+    ``GitSnapshot`` persisted at handoff time — a historical observation, never proof
+    of current working tree reality.
+    """
+
+    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 HandoffTestStatus(BaseModel):
+    """Canonical TEST STATUS section.
+
+    CortexShift has no durable verified test record in Phase 5. A provider process
+    exiting with code 0 does not prove that project tests passed, so ``known`` stays
+    False and the summary states the unknown honestly.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    known: bool = False
+    summary: str
+
+
+class HandoffSourceSession(BaseModel):
+    """Metadata of the CortexShift Session the work is being handed off from.
+
+    Derived strictly from durable CortexShift session records. Provider-native
+    transcripts, conversation histories, and hidden reasoning are never read.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    session_id: str
+    provider_id: ProviderId
+    status: SessionStatus
+    started_at: datetime
+    ended_at: datetime | None = None
+    exit_reason: SessionExitReason | None = None
+    exit_code: int | None = None
+
+
+class HandoffPayload(BaseModel):
+    """Canonical, provider-independent point-in-time engineering context.
+
+    Built deterministically from durable local state (canonical Project, canonical Task,
+    previous CortexShift Session metadata, live repository inspection, and the Git
+    snapshot persisted at handoff time). Generating this payload never requires the
+    outgoing provider to be installed, running, or able to answer.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    protocol_version: int = HANDOFF_PROTOCOL_VERSION
+    generated_at: datetime = Field(default_factory=utc_now)
+
+    # PROJECT
+    project_name: str
+    project_root: str
+
+    # Task identity
+    task_id: str
+    task_title: str
+    task_status: str
+
+    # Canonical protocol sections
+    original_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)
+    important_decisions: list[str] = Field(default_factory=list)
+    decisions_known: bool = False
+    files_touched: list[str] = Field(default_factory=list)
+    test_status: HandoffTestStatus
+    known_issues: list[str] = Field(default_factory=list)
+    git_state: HandoffGitState
+    do_not_redo: list[str] = Field(default_factory=list)
+    recommended_next_action: str
+
+    # Provenance
+    source_session: HandoffSourceSession
+    target_provider_id: ProviderId
+    operator_note: str | None = None
+    source_checkpoint_id: str | None = None
+    source_checkpoint_kind: str | None = None
+    source_checkpoint_created_at: datetime | None = None
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+def generate_handoff_id() -> str:
+    """Generate default ID for handoff records."""
+    return generate_id("handoff")
+
+
+class HandoffRecord(BaseModel):
+    """Orchestration and delivery metadata wrapping a canonical handoff payload.
+
+    The record tracks which Task moved between which CortexShift Sessions and providers,
+    which Git snapshot was captured, and whether delivery ultimately succeeded. Rendered
+    provider prompts and provider responses are deliberately not part of this record.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=generate_handoff_id)
+    protocol_version: int = HANDOFF_PROTOCOL_VERSION
+
+    project_id: str
+    task_id: str
+
+    source_session_id: str
+    source_provider_id: ProviderId
+    target_provider_id: ProviderId
+
+    source_checkpoint_id: str | None = None
+    git_snapshot_id: str | None = None
+    target_session_id: str | None = None
+
+    status: HandoffStatus = HandoffStatus.PREPARED
+    payload: HandoffPayload
+
+    created_at: datetime = Field(default_factory=utc_now)
+    delivered_at: datetime | None = None
+    failure_code: HandoffFailureCode | None = None
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def mark_delivered(
+        self,
+        target_session_id: str | None = None,
+        delivered_at: datetime | None = None,
+    ) -> "HandoffRecord":
+        """Return a copy marked as delivered, optionally binding the target Session."""
+        return self.model_copy(
+            update={
+                "status": HandoffStatus.DELIVERED,
+                "delivered_at": delivered_at or utc_now(),
+                "target_session_id": target_session_id or self.target_session_id,
+                "failure_code": None,
+            }
+        )
+
+    def mark_failed(
+        self,
+        failure_code: HandoffFailureCode,
+        target_session_id: str | None = None,
+    ) -> "HandoffRecord":
+        """Return a copy marked as failed with a safe machine classification."""
+        return self.model_copy(
+            update={
+                "status": HandoffStatus.FAILED,
+                "failure_code": failure_code,
+                "target_session_id": target_session_id or self.target_session_id,
+            }
+        )

cortexshift/domain/identifiers.py

@@ -0,0 +1,27 @@
+"""Stable identifier generation and timezone-aware timestamp utilities."""
+
+import uuid
+from datetime import UTC, datetime
+
+
+def generate_id(prefix: str) -> str:
+    """Generate a collision-resistant, human-readable prefixed identifier.
+
+    Format: `<prefix>_<uuid4_hex>` (e.g., `proj_1234567890abcdef...`).
+
+    Args:
+        prefix: Short entity prefix (e.g., 'proj', 'task', 'sess', 'cp', 'handoff').
+
+    Returns:
+        A unique, stable identifier string.
+    """
+    clean_prefix = prefix.strip().lower()
+    return f"{clean_prefix}_{uuid.uuid4().hex}"
+
+
+def utc_now() -> datetime:
+    """Return the current timezone-aware UTC datetime.
+
+    Avoids naive datetimes across all domain and persistence boundaries.
+    """
+    return datetime.now(UTC)

cortexshift/domain/launch.py

@@ -0,0 +1,58 @@
+"""Domain model representing the launch specification for a native provider process."""
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cortexshift.domain.provider import ProviderId
+
+
+class LaunchSpecification(BaseModel):
+    """Immutable specification for launching a native provider process.
+
+    Contains the exact argument list, working directory, and metadata needed
+    to spawn an interactive or headless provider session.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: ProviderId
+    executable: str
+    cwd: Path
+    argv: list[str]
+    native_session_id: str | None = None
+    interactive: bool = True
+    initial_prompt_supported: bool = True
+    prompt_supplied: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    env: dict[str, str] = Field(default_factory=dict)
+
+    def to_redacted_argv(self) -> list[str]:
+        """Return the argument list with any raw prompt replaced with '<prompt>'.
+
+        Preserves the executable and option flags while redacting prompt text.
+        """
+        if not self.prompt_supplied:
+            return list(self.argv)
+
+        # For providers where prompt is passed as the last positional argument
+        redacted = list(self.argv)
+        if len(redacted) > 1:
+            redacted[-1] = "<prompt>"
+        return redacted
+
+    def to_redacted_dict(self) -> dict[str, Any]:
+        """Return a dictionary representation suitable for logs and dry-run diagnostics.
+
+        Guarantees that raw user prompt contents are never leaked.
+        """
+        return {
+            "provider_id": str(self.provider_id),
+            "executable": self.executable,
+            "cwd": str(self.cwd),
+            "argv": self.to_redacted_argv(),
+            "interactive": self.interactive,
+            "initial_prompt_supported": self.initial_prompt_supported,
+            "prompt_supplied": self.prompt_supplied,
+        }

cortexshift/domain/mcp_binding.py

@@ -0,0 +1,81 @@
+"""Trusted managed-session binding handed to a provider-spawned MCP server.
+
+A provider CLI, not CortexShift, spawns the CortexShift MCP server. The binding below is
+the only channel through which CortexShift's own launch path states which project, task,
+CortexShift session, provider, and execution mode that server is bound to. It is minted
+exclusively from persisted state at launch time and is never assembled from provider or
+model input.
+"""
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from cortexshift.domain.provider import ProviderId
+from cortexshift.domain.session import Session
+
+ENV_PROJECT_ROOT = "CORTEXSHIFT_PROJECT_ROOT"
+ENV_TASK_ID = "CORTEXSHIFT_TASK_ID"
+ENV_SESSION_ID = "CORTEXSHIFT_SESSION_ID"
+ENV_PROVIDER_ID = "CORTEXSHIFT_PROVIDER_ID"
+ENV_MCP_READ_ONLY = "CORTEXSHIFT_MCP_READ_ONLY"
+
+#: Every variable the managed binding owns. A launch specification may add environment of
+#: its own, but never these: the binding is the single authority over execution context.
+BINDING_ENV_VARS = (
+    ENV_PROJECT_ROOT,
+    ENV_TASK_ID,
+    ENV_SESSION_ID,
+    ENV_PROVIDER_ID,
+    ENV_MCP_READ_ONLY,
+)
+
+
+class McpSessionBinding(BaseModel):
+    """Canonical managed execution context for one provider launch.
+
+    The MCP server re-validates every field against SQLite before granting write tools, so
+    this object asserts an identity rather than a permission.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    project_root: Path
+    task_id: str
+    session_id: str
+    provider_id: ProviderId
+    read_only: bool = False
+
+    @field_validator("task_id", "session_id")
+    @classmethod
+    def _reject_blank(cls, value: str) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError("Managed MCP binding identifiers cannot be blank.")
+        return cleaned
+
+    @classmethod
+    def from_session(
+        cls,
+        session: Session,
+        project_root: Path,
+        read_only: bool = False,
+    ) -> "McpSessionBinding":
+        """Mint a binding from a persisted Session, the only trusted source of identity."""
+        return cls(
+            project_root=project_root,
+            task_id=session.task_id,
+            session_id=session.id,
+            provider_id=session.provider_id,
+            read_only=read_only,
+        )
+
+    def to_env(self) -> dict[str, str]:
+        """Render the binding as the environment variables the MCP server resolves."""
+        return {
+            ENV_PROJECT_ROOT: str(self.project_root),
+            ENV_TASK_ID: self.task_id,
+            ENV_SESSION_ID: self.session_id,
+            ENV_PROVIDER_ID: str(self.provider_id),
+            ENV_MCP_READ_ONLY: "1" if self.read_only else "0",
+        }

cortexshift/domain/native_session.py

@@ -0,0 +1,19 @@
+"""Provider-native identity capabilities, independent of orchestration history."""
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NativeSessionCapabilities:
+    supports_exact_resume: bool = False
+    can_allocate_native_id_before_launch: bool = False
+    can_capture_native_id_during_bootstrap: bool = False
+    can_resume_with_followup_context: bool = False
+    requires_model_turn_for_handoff_resume: bool = False
+    supports_managed_new_session: bool = False
+
+
+def valid_native_id(value: str | None) -> bool:
+    """Reject empty IDs, option injection and control characters; IDs remain opaque."""
+    return bool(value and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,255}", value))

cortexshift/domain/project.py

@@ -0,0 +1,37 @@
+"""Domain model for a CortexShift Project."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from cortexshift.domain.identifiers import generate_id, utc_now
+
+
+def generate_project_id() -> str:
+    """Generate default ID for projects."""
+    return generate_id("proj")
+
+
+class Project(BaseModel):
+    """Represents a software project and repository managed by CortexShift.
+
+    Projects outlive individual tasks and contain long-lived memory such as
+    architecture invariants, conventions, and repository location.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=generate_project_id)
+    name: str
+    repo_path: str
+    created_at: datetime = Field(default_factory=utc_now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name_not_empty(cls, v: str) -> str:
+        stripped = v.strip()
+        if not stripped:
+            raise ValueError("Project name cannot be empty or blank.")
+        return stripped

cortexshift/domain/provider.py

@@ -0,0 +1,67 @@
+"""Domain models for extensible provider identification and capabilities."""
+
+import re
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProviderId(str):
+    """Extensible provider identifier.
+
+    Unlike a closed enum, ProviderId accepts any valid identifier matching
+    `^[a-z0-9][a-z0-9_-]{0,63}$`. This enables future agents (e.g., 'claude',
+    'codex', 'antigravity', 'kimi', 'aider') without core domain changes.
+    """
+
+    _PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+    def __new__(cls, value: str) -> "ProviderId":
+        cleaned = value.strip().lower()
+        if not cls._PATTERN.match(cleaned):
+            raise ValueError(
+                f"Invalid provider ID '{value}'. Must match pattern: ^[a-z0-9][a-z0-9_-]{{0,63}}$"
+            )
+        return super().__new__(cls, cleaned)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> Any:
+        from pydantic_core import core_schema
+
+        def validate(v: Any) -> "ProviderId":
+            if isinstance(v, ProviderId):
+                return v
+            if isinstance(v, str):
+                return ProviderId(v)
+            raise ValueError(f"Expected string or ProviderId, got {type(v)}")
+
+        return core_schema.no_info_after_validator_function(
+            validate,
+            core_schema.str_schema(),
+            serialization=core_schema.to_string_ser_schema(),
+        )
+
+
+# Standard canonical provider constants for common reference
+PROVIDER_CLAUDE = ProviderId("claude")
+PROVIDER_CODEX = ProviderId("codex")
+PROVIDER_ANTIGRAVITY = ProviderId("antigravity")
+
+
+class ProviderCapabilities(BaseModel):
+    """Declared capabilities of a coding agent provider.
+
+    Defines what operational modes and features an agent CLI supports.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: ProviderId
+    display_name: str
+    supports_interactive: bool = True
+    supports_headless: bool = False
+    supports_native_resume: bool = False
+    supports_structured_output: bool = False
+    supports_mcp: bool = False
+    supports_usage_metrics: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)