cortexshift 0.1.0__py3-none-any.whl

cortexshift/application/native_session.py

@@ -0,0 +1,65 @@
+"""Exact resume selection from canonical CortexShift records only."""
+
+from cortexshift.domain.errors import (
+    NativeResumeError,
+    SessionNotFoundError,
+    SessionTaskMismatchError,
+)
+from cortexshift.domain.native_session import NativeSessionCapabilities, valid_native_id
+from cortexshift.domain.provider import ProviderId
+from cortexshift.domain.session import Session, SessionExitReason, SessionStatus
+from cortexshift.ports.session_store import SessionStore
+
+
+def is_native_resumable(session: Session, capabilities: NativeSessionCapabilities) -> bool:
+    """Require a known ID and evidence that the provider process actually launched.
+
+    An allocated ID on an unfinished or spawn-failed invocation is not enough.
+    Exit evidence remains valid even when a launched process crashed or was interrupted.
+    """
+    return (
+        capabilities.supports_exact_resume
+        and valid_native_id(session.native_session_id)
+        and session.status
+        in (SessionStatus.COMPLETED, SessionStatus.INTERRUPTED, SessionStatus.FAILED)
+        and session.exit_code is not None
+        and session.exit_reason != SessionExitReason.SPAWN_FAILED
+    )
+
+
+def select_native_session(
+    store: SessionStore,
+    task_id: str,
+    provider_id: ProviderId,
+    capabilities: NativeSessionCapabilities,
+    explicit_session_id: str | None = None,
+) -> Session | None:
+    if explicit_session_id is not None:
+        session = store.get_session(explicit_session_id)
+        if session is None:
+            raise SessionNotFoundError(explicit_session_id)
+        if session.task_id != task_id:
+            raise SessionTaskMismatchError(explicit_session_id, task_id)
+        if session.provider_id != provider_id:
+            raise NativeResumeError("The selected CortexShift Session belongs to another provider.")
+        if not is_native_resumable(session, capabilities):
+            raise NativeResumeError("The selected CortexShift Session is not exactly resumable.")
+        return session
+
+    return next(
+        (
+            session
+            for session in store.list_sessions(task_id=task_id, limit=None)
+            if session.provider_id == provider_id and is_native_resumable(session, capabilities)
+        ),
+        None,
+    )
+
+
+def native_capabilities(adapter: object) -> NativeSessionCapabilities:
+    """Unsupported adapters honestly advertise no native continuity."""
+    from cortexshift.ports.native_session import ProviderNativeSessionAdapter
+
+    if isinstance(adapter, ProviderNativeSessionAdapter):
+        return adapter.get_native_capabilities()
+    return NativeSessionCapabilities()

cortexshift/application/recovery_service.py

@@ -0,0 +1,235 @@
+"""Application service for crash recovery and stale session reconciliation."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cortexshift.adapters.git.inspector import GitRepositoryInspector
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.adapters.workspace_lease import FileWorkspaceLeaseManager
+from cortexshift.application.checkpoint_builder import CheckpointBuilder
+from cortexshift.application.handoff_builder import derive_files_touched
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.domain.checkpoint import CheckpointKind
+from cortexshift.domain.errors import (
+    GitProbeError,
+    NoActiveTaskError,
+    ProjectNotInitializedError,
+    WorkspaceLockedError,
+)
+from cortexshift.domain.git import RepositoryInspectionStatus
+from cortexshift.domain.identifiers import utc_now
+from cortexshift.domain.session import SessionExitReason, SessionStatus
+from cortexshift.ports.repository import RepositoryInspector
+from cortexshift.ports.workspace_lease import WorkspaceLeaseManager
+
+
+class RecoveryReport(BaseModel):
+    """Structured representation of crash recovery results."""
+
+    model_config = ConfigDict(frozen=True)
+
+    project_id: str
+    task_id: str
+    task_title: str
+    stale_session_ids: list[str] = Field(default_factory=list)
+    reconciled_session_ids: list[str] = Field(default_factory=list)
+    checkpoint_id: str | None = None
+    git_snapshot_id: str | None = None
+    repository_status: RepositoryInspectionStatus
+    dirty: bool = False
+    files_touched: list[str] = Field(default_factory=list)
+    dry_run: bool = False
+    created_at: datetime = Field(default_factory=utc_now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RecoveryService:
+    """Coordinates crash recovery, lease acquisition, and session reconciliation."""
+
+    def __init__(
+        self,
+        inspector: RepositoryInspector | None = None,
+        lease_manager: WorkspaceLeaseManager | None = None,
+    ) -> None:
+        self._inspector = inspector or GitRepositoryInspector()
+        self._lease_manager = lease_manager or FileWorkspaceLeaseManager()
+
+    def recover(
+        self,
+        start_dir: Path | str | None = None,
+        *,
+        dry_run: bool = False,
+    ) -> RecoveryReport:
+        """Reconcile interrupted orchestration sessions and capture a Recovery Checkpoint.
+
+        Requires an exclusive workspace lease to verify no active CortexShift provider
+        process currently owns the workspace.
+        """
+        start_path = Path(start_dir) if start_dir is not None else None
+        project_root = ProjectLocator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = ProjectLocator.get_database_path(project_root)
+        store = SQLiteStateStore(db_path, auto_migrate=False)
+
+        try:
+            project = store.get_default_project()
+            if project is None:
+                raise ProjectNotInitializedError()
+
+            active_task_id = store.get_active_task_id(project.id)
+            if not active_task_id:
+                raise NoActiveTaskError()
+
+            task = store.get_task(active_task_id)
+            if task is None:
+                raise NoActiveTaskError()
+
+            lease = self._lease_manager.get_lease(Path(project.repo_path))
+
+            if dry_run:
+                # Probe lease non-destructively
+                if not lease.acquire():
+                    raise WorkspaceLockedError(lock_path=lease.lock_path)
+                lease.release()
+
+                # Find stale sessions
+                sessions = store.list_sessions(task_id=task.id, limit=None)
+                stale_sessions = [
+                    s
+                    for s in sessions
+                    if s.status in (SessionStatus.INITIALIZING, SessionStatus.RUNNING)
+                ]
+                stale_ids = [s.id for s in stale_sessions]
+
+                inspection = self._inspector.inspect(
+                    project_root=Path(project.repo_path),
+                    project_id=project.id,
+                )
+                if inspection.status == RepositoryInspectionStatus.PROBE_ERROR:
+                    raise GitProbeError(
+                        inspection.diagnostic
+                        or "Git repository inspection failed during recovery probe."
+                    )
+
+                dirty = inspection.snapshot.dirty if inspection.snapshot else False
+                files_touched = derive_files_touched(inspection)
+
+                return RecoveryReport(
+                    project_id=project.id,
+                    task_id=task.id,
+                    task_title=task.title,
+                    stale_session_ids=stale_ids,
+                    reconciled_session_ids=stale_ids,
+                    checkpoint_id=None,
+                    git_snapshot_id=None,
+                    repository_status=inspection.status,
+                    dirty=dirty,
+                    files_touched=files_touched,
+                    dry_run=True,
+                    metadata={
+                        "would_reconcile": bool(stale_sessions),
+                        "would_create_checkpoint": bool(stale_sessions),
+                    },
+                )
+
+            # Non-dry-run: acquire lease
+            if not lease.acquire():
+                raise WorkspaceLockedError(lock_path=lease.lock_path)
+
+            try:
+                sessions = store.list_sessions(task_id=task.id, limit=None)
+                stale_sessions = [
+                    s
+                    for s in sessions
+                    if s.status in (SessionStatus.INITIALIZING, SessionStatus.RUNNING)
+                ]
+                stale_ids = [s.id for s in stale_sessions]
+
+                inspection = self._inspector.inspect(
+                    project_root=Path(project.repo_path),
+                    project_id=project.id,
+                )
+                if inspection.status == RepositoryInspectionStatus.PROBE_ERROR:
+                    raise GitProbeError(
+                        inspection.diagnostic or "Git repository inspection failed during recovery."
+                    )
+
+                dirty = inspection.snapshot.dirty if inspection.snapshot else False
+                files_touched = derive_files_touched(inspection)
+
+                if not stale_sessions:
+                    # Predictable no-op when no stale sessions exist
+                    return RecoveryReport(
+                        project_id=project.id,
+                        task_id=task.id,
+                        task_title=task.title,
+                        stale_session_ids=[],
+                        reconciled_session_ids=[],
+                        checkpoint_id=None,
+                        git_snapshot_id=None,
+                        repository_status=inspection.status,
+                        dirty=dirty,
+                        files_touched=files_touched,
+                        dry_run=False,
+                        metadata={"message": "No stale sessions found to recover."},
+                    )
+
+                # Save Git snapshot if ready
+                snapshot_id: str | None = None
+                if (
+                    inspection.status == RepositoryInspectionStatus.READY
+                    and inspection.snapshot is not None
+                ):
+                    store.save_snapshot(inspection.snapshot)
+                    snapshot_id = inspection.snapshot.id
+
+                # Recovery Checkpoint associates with newest stale session
+                primary_stale = stale_sessions[0]
+                checkpoint = CheckpointBuilder.build(
+                    project=project,
+                    task=task,
+                    inspection=inspection,
+                    kind=CheckpointKind.RECOVERY,
+                    snapshot_id=snapshot_id,
+                    session=primary_stale,
+                    metadata={"reconciled_session_ids": stale_ids},
+                )
+                store.save_checkpoint(checkpoint)
+
+                # Reconcile all stale sessions
+                recovery_time = utc_now()
+                reconciled_ids: list[str] = []
+                for s in stale_sessions:
+                    reconciled = s.model_copy(
+                        update={
+                            "status": SessionStatus.INTERRUPTED,
+                            "exit_reason": SessionExitReason.UNEXPECTED_TERMINATION,
+                            "reconciled_at": recovery_time,
+                        }
+                    )
+                    store.save_session(reconciled)
+                    reconciled_ids.append(reconciled.id)
+
+                return RecoveryReport(
+                    project_id=project.id,
+                    task_id=task.id,
+                    task_title=task.title,
+                    stale_session_ids=stale_ids,
+                    reconciled_session_ids=reconciled_ids,
+                    checkpoint_id=checkpoint.id,
+                    git_snapshot_id=snapshot_id,
+                    repository_status=inspection.status,
+                    dirty=dirty,
+                    files_touched=files_touched,
+                    dry_run=False,
+                    metadata={"reconciled_count": len(reconciled_ids)},
+                )
+            finally:
+                lease.release()
+        finally:
+            store.close()

cortexshift/application/repository_service.py

@@ -0,0 +1,146 @@
+"""Application service for Git repository inspection and snapshot persistence."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from cortexshift.adapters.git.inspector import GitRepositoryInspector
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.domain.errors import (
+    GitNotInstalledError,
+    GitProbeError,
+    GitProbeTimeoutError,
+    NotAGitRepositoryError,
+    ProjectNotInitializedError,
+)
+from cortexshift.domain.git import (
+    GitSnapshot,
+    RepositoryInspection,
+    RepositoryInspectionStatus,
+)
+from cortexshift.domain.project import Project
+from cortexshift.ports.repository import RepositoryInspector, RepositorySnapshotStore
+
+
+class RepositoryService:
+    """Coordinates live Git repository inspection and snapshot persistence.
+
+    Enforces architecture layering:
+    - Never executes raw subprocess commands directly (delegates to RepositoryInspector).
+    - Never executes raw SQL statements directly (delegates to RepositorySnapshotStore).
+    """
+
+    def __init__(
+        self,
+        inspector: RepositoryInspector | None = None,
+        store: RepositorySnapshotStore | None = None,
+        locator: type[ProjectLocator] = ProjectLocator,
+    ) -> None:
+        self._inspector = inspector or GitRepositoryInspector()
+        self._store = store
+        self._locator = locator
+
+    @contextmanager
+    def _resolve_project_and_store(
+        self, start_path: Path | None = None
+    ) -> Iterator[tuple[Path, Project, RepositorySnapshotStore]]:
+        """Locate the initialized project and yield its snapshot store.
+
+        A store opened here is closed on exit. An injected store belongs to its caller
+        and is left open, so callers that share one connection (the MCP server, for
+        instance) keep working.
+        """
+        project_root = self._locator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        if self._store is not None:
+            store = self._store
+            # If store is also a StateStore, fetch default project
+            if hasattr(store, "get_default_project"):
+                project = store.get_default_project()
+                if project is None:
+                    raise ProjectNotInitializedError()
+            else:
+                project = Project(
+                    id="proj_resolved",
+                    name=project_root.name,
+                    repo_path=str(project_root),
+                )
+            yield project_root, project, store
+            return
+
+        db_path = self._locator.get_database_path(project_root)
+        sqlite_store = SQLiteStateStore(db_path, auto_migrate=True)
+        try:
+            project = sqlite_store.get_default_project()
+            if project is None:
+                raise ProjectNotInitializedError()
+            yield project_root, project, sqlite_store
+        finally:
+            sqlite_store.close()
+
+    def inspect_repository(self, start_path: Path | None = None) -> RepositoryInspection:
+        """Perform a live, non-persisting inspection of the repository."""
+        with self._resolve_project_and_store(start_path) as (project_root, project, _):
+            return self._inspector.inspect(project_root=project_root, project_id=project.id)
+
+    def capture_snapshot(self, start_path: Path | None = None) -> GitSnapshot:
+        """Perform live inspection and persist the snapshot if successful.
+
+        Raises:
+            GitNotInstalledError: If Git is not found in PATH.
+            NotAGitRepositoryError: If the project is not in a Git repository.
+            GitProbeTimeoutError: If inspection timed out.
+            GitProbeError: If inspection failed.
+        """
+        with self._resolve_project_and_store(start_path) as (project_root, project, store):
+            return self._capture(project_root, project, store)
+
+    def _capture(
+        self,
+        project_root: Path,
+        project: Project,
+        store: RepositorySnapshotStore,
+    ) -> GitSnapshot:
+        """Inspect the working tree and persist the resulting snapshot."""
+        inspection = self._inspector.inspect(project_root=project_root, project_id=project.id)
+
+        if inspection.status == RepositoryInspectionStatus.GIT_NOT_INSTALLED:
+            raise GitNotInstalledError(
+                inspection.diagnostic or "Git executable was not found in PATH."
+            )
+
+        if inspection.status == RepositoryInspectionStatus.NOT_GIT_REPOSITORY:
+            raise NotAGitRepositoryError(
+                inspection.diagnostic or "This CortexShift project is not inside a Git repository."
+            )
+
+        if inspection.status == RepositoryInspectionStatus.PROBE_ERROR:
+            diag = inspection.diagnostic or "Git repository inspection failed."
+            if "timed out" in diag.lower():
+                raise GitProbeTimeoutError(diag)
+            raise GitProbeError(diag)
+
+        if inspection.snapshot is None:
+            raise GitProbeError("No repository snapshot was generated.")
+
+        store.save_snapshot(inspection.snapshot)
+        return inspection.snapshot
+
+    def list_snapshots(
+        self,
+        project_id: str | None = None,
+        limit: int = 10,
+        start_path: Path | None = None,
+    ) -> list[GitSnapshot]:
+        """List historical snapshots for a project, newest first."""
+        with self._resolve_project_and_store(start_path) as (_, project, store):
+            pid = project_id or project.id
+            return store.list_snapshots(project_id=pid, limit=limit)
+
+    def get_snapshot(self, snapshot_id: str, start_path: Path | None = None) -> GitSnapshot | None:
+        """Retrieve a stored snapshot by ID."""
+        with self._resolve_project_and_store(start_path) as (_, _, store):
+            return store.get_snapshot(snapshot_id)

cortexshift/application/resume_service.py

@@ -0,0 +1,124 @@
+"""Exact native resume without creating a handoff or repository snapshot."""
+
+import sys
+from pathlib import Path
+
+from cortexshift.adapters.providers.antigravity import (
+    ANTIGRAVITY_MCP_MISSING_NOTICE,
+    is_antigravity_mcp_configured,
+)
+from cortexshift.application.native_session import select_native_session
+from cortexshift.application.run_service import DryRunResult, RunService
+from cortexshift.application.session_launcher import ProviderSessionLauncher
+from cortexshift.domain.errors import NativeResumeError, TerminalRequiredError, WorkspaceLockedError
+from cortexshift.domain.provider import PROVIDER_ANTIGRAVITY
+from cortexshift.domain.session import Session
+from cortexshift.ports.native_session import ProviderNativeSessionAdapter
+from cortexshift.ports.provider import ManagedMcpBinder
+
+
+class ResumeDryRunResult(DryRunResult):
+    source_session_id: str
+    native_session_id: str
+    native_session_known: bool = True
+    resume_strategy: str = "exact_native_id"
+    bootstrap_model_turn_required: bool = False
+
+    def to_dict(self) -> dict[str, object]:
+        return self.model_dump(mode="json")
+
+
+class ResumeService(RunService):
+    """Share run context resolution and injected execution boundaries; never nest leases."""
+
+    def resume(
+        self,
+        provider_name: str,
+        session_id: str | None = None,
+        start_dir: Path | str | None = None,
+        *,
+        dry_run: bool = False,
+    ) -> Session | ResumeDryRunResult:
+        _, project, task, adapter, executable, store = self._resolve_context(
+            provider_name, start_dir
+        )
+        try:
+            if not isinstance(adapter, ProviderNativeSessionAdapter):
+                raise NativeResumeError("This provider does not support exact native resume.")
+
+            def select() -> Session:
+                source = select_native_session(
+                    store,
+                    task.id,
+                    adapter.provider_id,
+                    adapter.get_native_capabilities(),
+                    session_id,
+                )
+                if source is None:
+                    raise NativeResumeError(
+                        f"No exact resumable {adapter.display_name} native session is recorded "
+                        "for the active task. CortexShift will not guess a provider session. "
+                        "Start a new native session with run, or switch to this provider instead."
+                    )
+                return source
+
+            source = select()
+            assert source.native_session_id is not None
+            spec = adapter.build_exact_resume(
+                Path(project.repo_path), executable, source.native_session_id
+            )
+            if dry_run:
+                return ResumeDryRunResult(
+                    provider_id=adapter.provider_id,
+                    display_name=adapter.display_name,
+                    executable=executable,
+                    project_id=project.id,
+                    project_name=project.name,
+                    task_id=task.id,
+                    task_title=task.title,
+                    cwd=spec.cwd,
+                    argv=spec.to_redacted_argv(),
+                    mode="native_resume",
+                    source_session_id=source.id,
+                    native_session_id=source.native_session_id,
+                )
+            if not self._is_tty():
+                raise TerminalRequiredError(
+                    "Interactive resume requires a terminal (TTY). "
+                    f"Use cortexshift resume {provider_name} --dry-run to preview."
+                )
+            lease = self._lease_manager.get_lease(Path(project.repo_path))
+            if not lease.acquire():
+                raise WorkspaceLockedError(lock_path=lease.lock_path)
+            try:
+                # Select again under the lease in case another invocation just finished.
+                source = select()
+                assert source.native_session_id is not None
+                spec = adapter.build_exact_resume(
+                    Path(project.repo_path), executable, source.native_session_id
+                )
+                launcher = ProviderSessionLauncher(
+                    self._runner,
+                    store,
+                    checkpoint_service=self._checkpoint_service,
+                )
+                invocation = launcher.start_session(
+                    task.id,
+                    adapter.provider_id,
+                    native_session_id=source.native_session_id,
+                    resumed_from_session_id=source.id,
+                )
+                if str(adapter.provider_id) == str(
+                    PROVIDER_ANTIGRAVITY
+                ) and not is_antigravity_mcp_configured(Path(project.repo_path)):
+                    sys.stderr.write(f"\n{ANTIGRAVITY_MCP_MISSING_NOTICE}\n\n")
+
+                return launcher.run(
+                    invocation,
+                    spec,
+                    mcp_binder=adapter if isinstance(adapter, ManagedMcpBinder) else None,
+                )
+            finally:
+                lease.release()
+        finally:
+            store.close()