cortexshift 0.1.0__py3-none-any.whl

cortexshift/domain/session.py

@@ -0,0 +1,92 @@
+"""Domain model for a coding agent execution session."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cortexshift.domain.identifiers import generate_id, utc_now
+from cortexshift.domain.provider import ProviderId
+
+
+class SessionStatus(StrEnum):
+    """Execution status of an individual agent session.
+
+    Phase 4 Active Statuses:
+      - INITIALIZING: Session record created before process launch.
+      - RUNNING: Session process is actively executing.
+      - COMPLETED: Process exited normally with exit code 0.
+      - INTERRUPTED: Session was interrupted by user (SIGINT/Ctrl+C, exit code 130).
+      - FAILED: Session process exited with non-zero exit code or spawn failed.
+
+    Reserved Future Statuses (not emitted in Phase 4):
+      - ACTIVE: Reserved alias for active execution states.
+      - TIMED_OUT: Reserved for execution timeout policies.
+    """
+
+    INITIALIZING = "initializing"
+    RUNNING = "running"
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    INTERRUPTED = "interrupted"
+    FAILED = "failed"
+    TIMED_OUT = "timed_out"
+
+
+class SessionExitReason(StrEnum):
+    """Reason why an agent session concluded or halted.
+
+    Phase 4 Active Exit Reasons:
+      - NORMAL_COMPLETION: Native CLI process exited with code 0.
+      - USER_INTERRUPTED: User interrupted interactive session via SIGINT (Ctrl+C).
+      - PROCESS_CRASHED: Native CLI process exited with non-zero exit code.
+      - SPAWN_FAILED: Process runner failed to spawn the native CLI executable.
+
+    Reserved Future Exit Reasons (not emitted in Phase 4):
+      - QUOTA_EXHAUSTED: Reserved for future structured API quota exhaustion detection.
+      - RATE_LIMITED: Reserved for future provider rate limit detection.
+      - UNEXPECTED_TERMINATION: Reserved for unexpected external process termination.
+      - UNKNOWN: Reserved fallback for unclassifiable exits.
+
+    Note: Phase 4 does not infer quota exhaustion or rate limits from generic
+    non-zero exit codes. Generic non-zero process exits map strictly to PROCESS_CRASHED.
+    """
+
+    NORMAL_COMPLETION = "normal_completion"
+    USER_INTERRUPTED = "user_interrupted"
+    PROCESS_CRASHED = "process_crashed"
+    SPAWN_FAILED = "spawn_failed"
+
+    # Reserved for future phases (not emitted in Phase 4):
+    QUOTA_EXHAUSTED = "quota_exhausted"
+    RATE_LIMITED = "rate_limited"
+    UNEXPECTED_TERMINATION = "unexpected_termination"
+    UNKNOWN = "unknown"
+
+
+def generate_session_id() -> str:
+    """Generate default ID for sessions."""
+    return generate_id("sess")
+
+
+class Session(BaseModel):
+    """An execution session by a specific coding agent working on a task.
+
+    Sessions are transient worker executions; tasks outlast sessions.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=generate_session_id)
+    task_id: str
+    provider_id: ProviderId
+    native_session_id: str | None = None
+    resumed_from_session_id: str | None = None
+    status: SessionStatus = SessionStatus.INITIALIZING
+    started_at: datetime = Field(default_factory=utc_now)
+    ended_at: datetime | None = None
+    exit_reason: SessionExitReason | None = None
+    exit_code: int | None = None
+    reconciled_at: datetime | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)

cortexshift/domain/status.py

@@ -0,0 +1,40 @@
+"""Domain models representing project and task status."""
+
+from pydantic import BaseModel, ConfigDict
+
+from cortexshift.domain.task import TaskStatus
+
+
+class ProgressSummary(BaseModel):
+    """Summary counts of task progression items."""
+
+    model_config = ConfigDict(frozen=True)
+
+    completed: int = 0
+    remaining: int = 0
+    issues: int = 0
+
+
+class ActiveTaskSummary(BaseModel):
+    """Summary of the currently active task on a project."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    title: str
+    status: TaskStatus
+    objective: str
+    progress: ProgressSummary
+
+
+class ProjectStatus(BaseModel):
+    """Comprehensive status of an initialized CortexShift project."""
+
+    model_config = ConfigDict(frozen=True)
+
+    project_id: str
+    name: str
+    repo_path: str
+    state_file: str
+    schema_version: int
+    active_task: ActiveTaskSummary | None = None

cortexshift/domain/task.py

@@ -0,0 +1,191 @@
+"""Domain model for a CortexShift Task."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field, field_validator, model_validator
+
+from cortexshift.domain.identifiers import generate_id, utc_now
+
+# Canonical input bounds for task progress mutations. Shared by every adapter that
+# accepts operator or agent supplied task text (MCP tools, the TUI control center).
+MAX_CURRENT_WORK_CHARS = 2000
+MAX_ITEM_CHARS = 500
+MAX_ITEMS_PER_CALL = 50
+
+
+class TaskStatus(StrEnum):
+    """Lifecycle status of a persistent development task."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    BLOCKED = "blocked"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+
+
+def generate_task_id() -> str:
+    """Generate default ID for tasks."""
+    return generate_id("task")
+
+
+class Task(BaseModel):
+    """Represents a persistent development task.
+
+    The task is the central abstraction of CortexShift. Coding agents are temporary
+    workers operating sequentially on this task.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(default_factory=generate_task_id)
+    project_id: str
+    title: str
+    objective: str
+    requirements: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+    status: TaskStatus = TaskStatus.PENDING
+    completed_items: list[str] = Field(default_factory=list)
+    current_work: str | None = None
+    remaining_items: list[str] = Field(default_factory=list)
+    known_issues: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_completed_and_remaining(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            # Support both completed and completed_items
+            if "completed" in data and "completed_items" not in data:
+                data["completed_items"] = data.pop("completed")
+            # Support both remaining and remaining_items
+            if "remaining" in data and "remaining_items" not in data:
+                data["remaining_items"] = data.pop("remaining")
+        return data
+
+    @field_validator("title", "objective")
+    @classmethod
+    def validate_non_empty_strings(cls, v: str) -> str:
+        stripped = v.strip()
+        if not stripped:
+            raise ValueError("Field cannot be empty or blank.")
+        return stripped
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def completed(self) -> list[str]:
+        """Canonical alias for completed_items."""
+        return self.completed_items
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def remaining(self) -> list[str]:
+        """Canonical alias for remaining_items."""
+        return self.remaining_items
+
+    @property
+    def is_terminal(self) -> bool:
+        """Return True if the task is in a terminal state (cannot be resumed/activated)."""
+        return self.status in (TaskStatus.COMPLETED, TaskStatus.CANCELLED)
+
+    def mark_completed(self) -> "Task":
+        """Return a copy of this task marked as completed with updated timestamp."""
+        now = utc_now()
+        return self.model_copy(
+            update={
+                "status": TaskStatus.COMPLETED,
+                "updated_at": now,
+            }
+        )
+
+    def with_current_work(self, work: str | None) -> "Task":
+        """Return a copy of this task with updated current work and timestamp."""
+        now = utc_now()
+        cleaned = work.strip() if work is not None else None
+        return self.model_copy(
+            update={
+                "current_work": cleaned if cleaned else None,
+                "updated_at": now,
+            }
+        )
+
+    def add_completed_items(self, items: list[str]) -> "Task":
+        """Return a copy of this task with additional completed items (deduplicated)."""
+        new_items = list(self.completed_items)
+        existing_set = set(new_items)
+        for item in items:
+            cleaned = item.strip()
+            if cleaned and cleaned not in existing_set:
+                new_items.append(cleaned)
+                existing_set.add(cleaned)
+        return self.model_copy(
+            update={
+                "completed_items": new_items,
+                "updated_at": utc_now(),
+            }
+        )
+
+    def add_remaining_items(self, items: list[str]) -> "Task":
+        """Return a copy of this task with additional remaining items (deduplicated)."""
+        new_items = list(self.remaining_items)
+        existing_set = set(new_items)
+        for item in items:
+            cleaned = item.strip()
+            if cleaned and cleaned not in existing_set:
+                new_items.append(cleaned)
+                existing_set.add(cleaned)
+        return self.model_copy(
+            update={
+                "remaining_items": new_items,
+                "updated_at": utc_now(),
+            }
+        )
+
+    def add_known_issues(self, items: list[str]) -> "Task":
+        """Return a copy of this task with additional known issues (deduplicated)."""
+        new_items = list(self.known_issues)
+        existing_set = set(new_items)
+        for item in items:
+            cleaned = item.strip()
+            if cleaned and cleaned not in existing_set:
+                new_items.append(cleaned)
+                existing_set.add(cleaned)
+        return self.model_copy(
+            update={
+                "known_issues": new_items,
+                "updated_at": utc_now(),
+            }
+        )
+
+    def complete_items(self, items: list[str]) -> "Task":
+        """Return a copy with items marked completed and dropped from remaining.
+
+        This is the canonical "mark completed" rule: items are appended to
+        `completed_items` (deduplicated) and any exactly matching entry is removed from
+        `remaining_items`. It never completes the Task itself — see `mark_completed`.
+        """
+        cleaned = [stripped for item in items if (stripped := item.strip())]
+        if not cleaned:
+            return self
+
+        updated = self.add_completed_items(cleaned)
+        completed_set = set(cleaned)
+        return updated.model_copy(
+            update={
+                "remaining_items": [
+                    item for item in updated.remaining_items if item not in completed_set
+                ],
+                "updated_at": utc_now(),
+            }
+        )
+
+    def add_completed(self, items: list[str]) -> "Task":
+        """Alias for add_completed_items."""
+        return self.add_completed_items(items)
+
+    def add_remaining(self, items: list[str]) -> "Task":
+        """Alias for add_remaining_items."""
+        return self.add_remaining_items(items)

cortexshift/mcp/__init__.py

@@ -0,0 +1,38 @@
+"""CortexShift Model Context Protocol (MCP) shared state integration."""
+
+from cortexshift.mcp.context import (
+    ENV_MCP_READ_ONLY,
+    ENV_PROJECT_ROOT,
+    ENV_PROVIDER_ID,
+    ENV_SESSION_ID,
+    ENV_TASK_ID,
+    McpExecutionContext,
+    resolve_mcp_context,
+)
+from cortexshift.mcp.facade import McpApplicationFacade
+from cortexshift.mcp.models import (
+    CheckpointResult,
+    CreateCheckpointResult,
+    DecisionResult,
+    ProjectContextResult,
+    TaskMutationResult,
+)
+from cortexshift.mcp.server import create_mcp_server, run_mcp_server
+
+__all__ = [
+    "ENV_MCP_READ_ONLY",
+    "ENV_PROJECT_ROOT",
+    "ENV_PROVIDER_ID",
+    "ENV_SESSION_ID",
+    "ENV_TASK_ID",
+    "CheckpointResult",
+    "CreateCheckpointResult",
+    "DecisionResult",
+    "McpApplicationFacade",
+    "McpExecutionContext",
+    "ProjectContextResult",
+    "TaskMutationResult",
+    "create_mcp_server",
+    "resolve_mcp_context",
+    "run_mcp_server",
+]

cortexshift/mcp/context.py

@@ -0,0 +1,165 @@
+"""Execution context resolution and validation for CortexShift MCP server."""
+
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.domain.errors import McpContextError
+from cortexshift.domain.mcp_binding import (
+    ENV_MCP_READ_ONLY,
+    ENV_PROJECT_ROOT,
+    ENV_PROVIDER_ID,
+    ENV_SESSION_ID,
+    ENV_TASK_ID,
+)
+from cortexshift.domain.provider import ProviderId
+
+__all__ = [
+    "ENV_MCP_READ_ONLY",
+    "ENV_PROJECT_ROOT",
+    "ENV_PROVIDER_ID",
+    "ENV_SESSION_ID",
+    "ENV_TASK_ID",
+    "McpExecutionContext",
+    "resolve_mcp_context",
+]
+
+
+class McpExecutionContext(BaseModel):
+    """Canonical execution context binding the MCP server to local project state."""
+
+    model_config = ConfigDict(frozen=True)
+
+    project_root: Path
+    project_id: str
+    task_id: str | None = None
+    session_id: str | None = None
+    provider_id: ProviderId | None = None
+    managed_session: bool = False
+    read_only: bool = False
+
+    def can_mutate(self) -> bool:
+        """Return True if write operations are permitted in this context."""
+        return self.managed_session and not self.read_only
+
+
+def resolve_mcp_context(
+    project_root_override: Path | None = None,
+    store_override: SQLiteStateStore | None = None,
+    env_override: dict[str, str] | None = None,
+) -> tuple[McpExecutionContext, SQLiteStateStore]:
+    """Resolve and validate the canonical McpExecutionContext.
+
+    Validates:
+    - Project initialization and root resolution
+    - Session existence, task ownership, and provider identity (if session_id provided)
+    - Bound task existence and project membership
+    - Read-only enforcement for unmanaged invocations or explicit read-only flag
+
+    Returns:
+        A tuple of (McpExecutionContext, initialized SQLiteStateStore).
+
+    Raises:
+        McpContextError: If the context violates invariants or SQLite state is invalid.
+    """
+    env = os.environ if env_override is None else env_override
+
+    # 1. Resolve project root
+    explicit_root_str = env.get(ENV_PROJECT_ROOT)
+    candidate_root: Path | None = None
+    if project_root_override is not None:
+        candidate_root = project_root_override.resolve()
+    elif explicit_root_str:
+        candidate_root = Path(explicit_root_str).resolve()
+    else:
+        candidate_root = ProjectLocator.find_project_root()
+
+    if candidate_root is None or not ProjectLocator.is_initialized(candidate_root):
+        loc = candidate_root or Path.cwd()
+        raise McpContextError(f"No initialized CortexShift project found at or above '{loc}'.")
+
+    project_root = candidate_root.resolve()
+
+    # 2. Connect store and fetch project
+    store = (
+        store_override
+        if store_override is not None
+        else SQLiteStateStore(ProjectLocator.get_database_path(project_root))
+    )
+
+    project = store.get_default_project()
+    if project is None:
+        raise McpContextError(f"No project record found in database at {project_root}.")
+
+    if Path(project.repo_path).resolve() != project_root:
+        raise McpContextError(
+            f"Project root mismatch: record specifies '{project.repo_path}', "
+            f"but current root is '{project_root}'."
+        )
+
+    # 3. Read-only override
+    explicit_read_only = env.get(ENV_MCP_READ_ONLY, "0").strip().lower() in ("1", "true", "yes")
+
+    session_id = env.get(ENV_SESSION_ID)
+    env_task_id = env.get(ENV_TASK_ID)
+    env_provider_id = env.get(ENV_PROVIDER_ID)
+
+    if session_id:
+        # Managed invocation: must be strictly validated
+        session = store.get_session(session_id)
+        if session is None:
+            raise McpContextError(f"Session '{session_id}' not found in project '{project.id}'.")
+
+        if env_task_id and session.task_id != env_task_id:
+            raise McpContextError(
+                f"Session '{session_id}' task '{session.task_id}' does not match "
+                f"environment task '{env_task_id}'."
+            )
+
+        if env_provider_id and str(session.provider_id) != env_provider_id:
+            raise McpContextError(
+                f"Session '{session_id}' provider '{session.provider_id}' does not match "
+                f"environment provider '{env_provider_id}'."
+            )
+
+        task = store.get_task(session.task_id)
+        if task is None:
+            raise McpContextError(
+                f"Task '{session.task_id}' bound to session '{session_id}' not found."
+            )
+
+        if task.project_id != project.id:
+            raise McpContextError(f"Task '{task.id}' does not belong to project '{project.id}'.")
+
+        context = McpExecutionContext(
+            project_root=project_root,
+            project_id=project.id,
+            task_id=session.task_id,
+            session_id=session.id,
+            provider_id=session.provider_id,
+            managed_session=True,
+            read_only=explicit_read_only,
+        )
+    else:
+        # Unmanaged invocation: strictly read-only
+        candidate_task_id = env_task_id or store.get_active_task_id(project.id)
+        resolved_task_id: str | None = None
+        if candidate_task_id:
+            task = store.get_task(candidate_task_id)
+            if task and task.project_id == project.id:
+                resolved_task_id = task.id
+
+        context = McpExecutionContext(
+            project_root=project_root,
+            project_id=project.id,
+            task_id=resolved_task_id,
+            session_id=None,
+            provider_id=None,
+            managed_session=False,
+            read_only=True,
+        )
+
+    return context, store