cortexshift 0.1.0__py3-none-any.whl

cortexshift/application/run_service.py

@@ -0,0 +1,270 @@
+"""Application service for orchestrating native provider launch and session lifecycle."""
+
+import shutil
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from cortexshift.adapters.process_runner import SubprocessInteractiveProcessRunner
+from cortexshift.adapters.providers.antigravity import (
+    ANTIGRAVITY_MCP_MISSING_NOTICE,
+    AntigravityRuntimeAdapter,
+    is_antigravity_mcp_configured,
+)
+from cortexshift.adapters.providers.claude import ClaudeRuntimeAdapter
+from cortexshift.adapters.providers.codex import CodexRuntimeAdapter
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.adapters.workspace_lease import FileWorkspaceLeaseManager
+from cortexshift.application.checkpoint_service import CheckpointService
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.application.session_launcher import ProviderSessionLauncher
+from cortexshift.domain.errors import (
+    NoActiveTaskError,
+    ProjectNotInitializedError,
+    ProviderNotFoundError,
+    TerminalRequiredError,
+    UnknownProviderError,
+    WorkspaceLockedError,
+)
+from cortexshift.domain.launch import LaunchSpecification
+from cortexshift.domain.project import Project
+from cortexshift.domain.provider import (
+    PROVIDER_ANTIGRAVITY,
+    ProviderId,
+)
+from cortexshift.domain.session import Session
+from cortexshift.domain.task import Task
+from cortexshift.ports.process_runner import InteractiveProcessRunner
+from cortexshift.ports.provider import ManagedMcpBinder, ProviderRuntimeAdapter
+from cortexshift.ports.workspace_lease import WorkspaceLeaseManager
+
+
+class DryRunResult(BaseModel):
+    """Result of a dry-run provider launch preview."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: ProviderId
+    display_name: str
+    executable: str
+    project_id: str
+    project_name: str
+    task_id: str
+    task_title: str
+    cwd: Path
+    argv: list[str]
+    mode: str = "interactive"
+    prompt_supplied: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize dry-run result without leaking raw prompts."""
+        return {
+            "provider_id": str(self.provider_id),
+            "display_name": self.display_name,
+            "executable": self.executable,
+            "project_id": self.project_id,
+            "project_name": self.project_name,
+            "task_id": self.task_id,
+            "task_title": self.task_title,
+            "cwd": str(self.cwd),
+            "argv": self.argv,
+            "mode": self.mode,
+            "prompt_supplied": self.prompt_supplied,
+        }
+
+
+class ProviderRuntimeRegistry:
+    """Registry of supported provider runtime adapters."""
+
+    def __init__(self, adapters: list[ProviderRuntimeAdapter] | None = None) -> None:
+        self._adapters: dict[str, ProviderRuntimeAdapter] = {}
+        if adapters is None:
+            adapters = [
+                ClaudeRuntimeAdapter(),
+                CodexRuntimeAdapter(),
+                AntigravityRuntimeAdapter(),
+            ]
+        for adapter in adapters:
+            self._adapters[str(adapter.provider_id).lower()] = adapter
+
+    def get(self, provider_id_str: str) -> ProviderRuntimeAdapter | None:
+        return self._adapters.get(provider_id_str.strip().lower())
+
+    def list_supported_ids(self) -> list[str]:
+        return sorted(self._adapters.keys())
+
+
+class RunService:
+    """Orchestrates native provider process launching and session lifecycle."""
+
+    def __init__(
+        self,
+        registry: ProviderRuntimeRegistry | None = None,
+        process_runner: InteractiveProcessRunner | None = None,
+        lease_manager: WorkspaceLeaseManager | None = None,
+        which_fn: Callable[[str], str | None] | None = None,
+        is_tty_fn: Callable[[], bool] | None = None,
+        checkpoint_service: CheckpointService | None = None,
+    ) -> None:
+        self._registry = registry or ProviderRuntimeRegistry()
+        self._runner = process_runner or SubprocessInteractiveProcessRunner()
+        self._lease_manager = lease_manager or FileWorkspaceLeaseManager()
+        self._which = which_fn if which_fn is not None else (lambda cmd: shutil.which(cmd))
+        self._is_tty = is_tty_fn if is_tty_fn is not None else self._check_tty
+        self._checkpoint_service = checkpoint_service or CheckpointService()
+
+    @staticmethod
+    def _check_tty() -> bool:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+
+    def _resolve_context(
+        self,
+        provider_name: str,
+        start_dir: Path | str | None = None,
+    ) -> tuple[Path, Project, Task, ProviderRuntimeAdapter, str, SQLiteStateStore]:
+        """Resolve and validate project, active task, provider, and executable."""
+        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()
+
+            adapter = self._registry.get(provider_name)
+            if adapter is None:
+                raise UnknownProviderError(provider_name, self._registry.list_supported_ids())
+
+            resolved_executable = self._which(adapter.executable)
+            if not resolved_executable:
+                raise ProviderNotFoundError(f"{adapter.display_name} was not found in PATH.")
+
+            return project_root, project, task, adapter, resolved_executable, store
+        except Exception:
+            store.close()
+            raise
+
+    def dry_run(
+        self,
+        provider_name: str,
+        prompt: str | None = None,
+        start_dir: Path | str | None = None,
+    ) -> DryRunResult:
+        """Perform a dry-run preview of provider launch without side effects."""
+        project_root, project, task, adapter, resolved_executable, store = self._resolve_context(
+            provider_name, start_dir
+        )
+        try:
+            launch_spec = adapter.build_launch_spec(
+                project_root=Path(project.repo_path),
+                executable_path=resolved_executable,
+                prompt=prompt,
+            )
+
+            return DryRunResult(
+                provider_id=adapter.provider_id,
+                display_name=adapter.display_name,
+                executable=resolved_executable,
+                project_id=project.id,
+                project_name=project.name,
+                task_id=task.id,
+                task_title=task.title,
+                cwd=launch_spec.cwd,
+                argv=launch_spec.to_redacted_argv(),
+                mode="interactive",
+                prompt_supplied=launch_spec.prompt_supplied,
+            )
+        finally:
+            store.close()
+
+    def run(
+        self,
+        provider_name: str,
+        prompt: str | None = None,
+        start_dir: Path | str | None = None,
+        on_launch: Callable[[LaunchSpecification, Session, Task, Project], None] | None = None,
+    ) -> Session:
+        """Launch an interactive provider session and manage its lifecycle.
+
+        Args:
+            provider_name: Canonical identifier of provider (e.g. 'claude', 'codex', 'antigravity').
+            prompt: Optional initial prompt.
+            start_dir: Directory where the command was invoked.
+            on_launch: Optional callback executed immediately before spawning process.
+
+        Returns:
+            The finalized Session entity.
+        """
+        project_root, project, task, adapter, resolved_executable, store = self._resolve_context(
+            provider_name, start_dir
+        )
+
+        try:
+            # 1. Check TTY requirement
+            if not self._is_tty():
+                raise TerminalRequiredError(
+                    "Interactive provider launch requires a terminal (TTY).\n\n"
+                    f"To simulate provider launch non-interactively, use: "
+                    f"cortexshift run {provider_name} --dry-run"
+                )
+
+            # 2. Build launch specification (validates prompt capability before lease)
+            launch_spec = adapter.build_launch_spec(
+                project_root=Path(project.repo_path),
+                executable_path=resolved_executable,
+                prompt=prompt,
+            )
+
+            # 3. Acquire workspace lease
+            lease = self._lease_manager.get_lease(Path(project.repo_path))
+            if not lease.acquire():
+                raise WorkspaceLockedError(lock_path=lease.lock_path)
+
+            # 4. Delegate Session creation and lifecycle to the shared launcher
+            launcher = ProviderSessionLauncher(
+                process_runner=self._runner,
+                store=store,
+                checkpoint_service=self._checkpoint_service,
+            )
+            try:
+                session = launcher.start_session(
+                    task_id=task.id,
+                    provider_id=adapter.provider_id,
+                    native_session_id=launch_spec.native_session_id,
+                )
+
+                def _forward(spec: LaunchSpecification, current: Session) -> None:
+                    if on_launch:
+                        on_launch(spec, current, task, project)
+
+                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(
+                    session,
+                    launch_spec,
+                    on_launch=_forward,
+                    mcp_binder=adapter if isinstance(adapter, ManagedMcpBinder) else None,
+                )
+            finally:
+                lease.release()
+        finally:
+            store.close()

cortexshift/application/session_launcher.py

@@ -0,0 +1,183 @@
+"""Shared provider session lifecycle used by both `run` and `switch`.
+
+Extracted from ``RunService`` in Phase 5 so that launching a native provider and
+tracking its CortexShift Session lifecycle exists in exactly one place. The launcher
+assumes its caller has already resolved the project and task and already holds the
+exclusive workspace lease, which keeps `switch` from nesting a second advisory lock
+around the same workspace.
+"""
+
+import contextlib
+from collections.abc import Callable
+from typing import Any
+
+from cortexshift.domain.identifiers import utc_now
+from cortexshift.domain.launch import LaunchSpecification
+from cortexshift.domain.mcp_binding import McpSessionBinding
+from cortexshift.domain.provider import ProviderId
+from cortexshift.domain.session import Session, SessionExitReason, SessionStatus
+from cortexshift.ports.process_runner import InteractiveProcessRunner
+from cortexshift.ports.provider import ManagedMcpBinder
+from cortexshift.ports.session_store import SessionStore
+
+
+class ProviderSessionLauncher:
+    """Creates, runs, and finalizes CortexShift Sessions for native provider processes."""
+
+    def __init__(
+        self,
+        process_runner: InteractiveProcessRunner,
+        store: SessionStore,
+        checkpoint_service: Any | None = None,
+    ) -> None:
+        self._runner = process_runner
+        self._store = store
+        self._checkpoint_service = checkpoint_service
+
+    def start_session(
+        self,
+        task_id: str,
+        provider_id: ProviderId,
+        native_session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        resumed_from_session_id: str | None = None,
+    ) -> Session:
+        """Create and persist a running Session immediately before provider work begins."""
+        session = Session(
+            task_id=task_id,
+            provider_id=provider_id,
+            native_session_id=native_session_id,
+            resumed_from_session_id=resumed_from_session_id,
+            status=SessionStatus.RUNNING,
+            started_at=utc_now(),
+            metadata=metadata or {},
+        )
+        self._store.save_session(session)
+        return session
+
+    def attach_native_session_id(self, session: Session, native_session_id: str) -> Session:
+        """Bind a provider-native conversation identifier to an existing Session."""
+        updated = session.model_copy(update={"native_session_id": native_session_id})
+        self._store.save_session(updated)
+        return updated
+
+    def fail_session(
+        self,
+        session: Session,
+        exit_reason: SessionExitReason,
+        exit_code: int | None = None,
+    ) -> Session:
+        """Mark a Session failed before or instead of an interactive process run."""
+        updated = session.model_copy(
+            update={
+                "status": SessionStatus.FAILED,
+                "ended_at": utc_now(),
+                "exit_reason": exit_reason,
+                "exit_code": exit_code,
+            }
+        )
+        self._store.save_session(updated)
+        return updated
+
+    def run(
+        self,
+        session: Session,
+        launch_spec: LaunchSpecification,
+        on_launch: Callable[[LaunchSpecification, Session], None] | None = None,
+        mcp_binder: ManagedMcpBinder | None = None,
+    ) -> Session:
+        """Run the native provider process and finalize the Session lifecycle.
+
+        This is the only place a managed MCP binding is minted, and it is minted from the
+        persisted Session rather than from anything a provider or model supplied. Providers
+        that configure the CortexShift MCP server per launch declare the binding inside
+        that configuration, because a provider decides for itself how much of CortexShift's
+        environment the MCP server it spawns will actually see.
+
+        Generic non-zero exits map strictly to `process_crashed`; CortexShift never infers
+        quota exhaustion or rate limiting from an exit code. Spawn failures map to
+        `spawn_failed` and re-raise so the caller can classify the operation as failed.
+        """
+        try:
+            binding = McpSessionBinding.from_session(
+                session=session,
+                project_root=launch_spec.cwd,
+            )
+            if mcp_binder is not None:
+                launch_spec = mcp_binder.bind_managed_mcp(launch_spec, binding)
+
+            if on_launch:
+                on_launch(launch_spec, session)
+
+            # A launch specification may contribute environment of its own, but the trusted
+            # binding always wins: execution context is never negotiable by an adapter.
+            binding_env: dict[str, str] = dict(launch_spec.env)
+            binding_env.update(binding.to_env())
+
+            exit_code = self._runner.run_interactive(
+                argv=launch_spec.argv,
+                cwd=launch_spec.cwd,
+                env=binding_env,
+            )
+
+            ended_at = utc_now()
+            if exit_code == 0:
+                session = session.model_copy(
+                    update={
+                        "status": SessionStatus.COMPLETED,
+                        "ended_at": ended_at,
+                        "exit_code": 0,
+                        "exit_reason": SessionExitReason.NORMAL_COMPLETION,
+                    }
+                )
+            elif exit_code in (130, -2):
+                session = session.model_copy(
+                    update={
+                        "status": SessionStatus.INTERRUPTED,
+                        "ended_at": ended_at,
+                        "exit_code": 130,
+                        "exit_reason": SessionExitReason.USER_INTERRUPTED,
+                    }
+                )
+            else:
+                session = session.model_copy(
+                    update={
+                        "status": SessionStatus.FAILED,
+                        "ended_at": ended_at,
+                        "exit_code": exit_code,
+                        "exit_reason": SessionExitReason.PROCESS_CRASHED,
+                    }
+                )
+        except KeyboardInterrupt:
+            session = session.model_copy(
+                update={
+                    "status": SessionStatus.INTERRUPTED,
+                    "ended_at": utc_now(),
+                    "exit_code": 130,
+                    "exit_reason": SessionExitReason.USER_INTERRUPTED,
+                }
+            )
+        except Exception:
+            session = session.model_copy(
+                update={
+                    "status": SessionStatus.FAILED,
+                    "ended_at": utc_now(),
+                    "exit_reason": SessionExitReason.SPAWN_FAILED,
+                }
+            )
+            self._store.save_session(session)
+            raise
+
+        self._store.save_session(session)
+
+        # Automatic session-end checkpoint capture for completed, failed, or interrupted runs
+        if self._checkpoint_service is not None and hasattr(
+            self._checkpoint_service, "capture_session_end_checkpoint"
+        ):
+            with contextlib.suppress(Exception):
+                self._checkpoint_service.capture_session_end_checkpoint(
+                    session=session,
+                    store=self._store,
+                )
+
+        return session

cortexshift/application/session_service.py

@@ -0,0 +1,63 @@
+"""Application service for querying CortexShift session history."""
+
+from pathlib import Path
+
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.application.locator import ProjectLocator
+from cortexshift.domain.errors import ProjectNotInitializedError, SessionNotFoundError
+from cortexshift.domain.session import Session
+
+
+class SessionService:
+    """Provides querying capabilities for agent execution sessions."""
+
+    def __init__(self, project_locator: type[ProjectLocator] = ProjectLocator) -> None:
+        self._locator = project_locator
+
+    def list_sessions(
+        self,
+        start_dir: Path | str | None = None,
+        limit: int = 20,
+    ) -> list[Session]:
+        """List sessions for the current project, ordered newest first."""
+        start_path = Path(start_dir) if start_dir is not None else None
+        project_root = self._locator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = self._locator.get_database_path(project_root)
+        store = SQLiteStateStore(db_path, auto_migrate=False)
+        try:
+            project = store.get_default_project()
+            if project is None:
+                raise ProjectNotInitializedError()
+
+            return store.list_sessions(project_id=project.id, limit=limit)
+        finally:
+            store.close()
+
+    def get_session(
+        self,
+        session_id: str,
+        start_dir: Path | str | None = None,
+    ) -> Session:
+        """Retrieve a specific session by ID.
+
+        Raises:
+            ProjectNotInitializedError: If no project is found.
+            SessionNotFoundError: If the session ID does not exist.
+        """
+        start_path = Path(start_dir) if start_dir is not None else None
+        project_root = self._locator.find_project_root(start_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = self._locator.get_database_path(project_root)
+        store = SQLiteStateStore(db_path, auto_migrate=False)
+        try:
+            session = store.get_session(session_id)
+            if session is None:
+                raise SessionNotFoundError(session_id)
+            return session
+        finally:
+            store.close()

cortexshift/application/source_session.py

@@ -0,0 +1,62 @@
+"""Selection of the CortexShift Session a handoff originates from.
+
+Source selection reads only durable CortexShift session records. Provider transcript
+history, hidden conversation storage, and provider-native session databases are never
+consulted, and the outgoing provider is never contacted.
+"""
+
+from cortexshift.domain.errors import (
+    NoSourceSessionError,
+    SessionNotFoundError,
+    SessionTaskMismatchError,
+)
+from cortexshift.domain.session import Session, SessionExitReason
+from cortexshift.domain.task import Task
+from cortexshift.ports.session_store import SessionStore
+
+# How far back to look for a meaningful prior session on the active task.
+_SOURCE_LOOKUP_LIMIT = 100
+
+
+def _is_meaningful(session: Session) -> bool:
+    """Whether a session represents real prior agent work.
+
+    A session whose provider process never spawned contributed nothing, so it is not
+    preferred as a handoff source while an earlier real session exists.
+    """
+    return session.exit_reason != SessionExitReason.SPAWN_FAILED
+
+
+def select_source_session(
+    store: SessionStore,
+    task: Task,
+    explicit_session_id: str | None = None,
+) -> Session:
+    """Resolve the source Session for a handoff on the given active task.
+
+    With no explicit override, the most recent meaningful session on the active task
+    wins, falling back to the most recent session overall when every recorded session
+    failed to spawn.
+
+    Raises:
+        SessionNotFoundError: If an explicitly requested session does not exist.
+        SessionTaskMismatchError: If an explicit session belongs to a different task.
+        NoSourceSessionError: If the active task has no prior session at all.
+    """
+    if explicit_session_id:
+        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)
+        return session
+
+    sessions = store.list_sessions(task_id=task.id, limit=_SOURCE_LOOKUP_LIMIT)
+    if not sessions:
+        raise NoSourceSessionError()
+
+    for session in sessions:
+        if _is_meaningful(session):
+            return session
+
+    return sessions[0]

cortexshift/application/status_service.py

@@ -0,0 +1,73 @@
+"""Application service for assembling project status and active task metrics."""
+
+from pathlib import Path
+
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.application.locator import (
+    DATABASE_FILE_NAME,
+    STATE_DIR_NAME,
+    ProjectLocator,
+)
+from cortexshift.domain.errors import ProjectNotInitializedError
+from cortexshift.domain.status import ActiveTaskSummary, ProgressSummary, ProjectStatus
+
+
+class ProjectStatusService:
+    """Queries project persistence to construct canonical status models."""
+
+    def __init__(self, locator: type[ProjectLocator] = ProjectLocator) -> None:
+        self.locator = locator
+
+    def get_status(self, start_path: Path | str | None = None) -> ProjectStatus:
+        """Inspect the project root for the given path and return structured status.
+
+        Args:
+            start_path: Starting path or project directory. Defaults to Path.cwd().
+
+        Returns:
+            A populated ProjectStatus entity.
+
+        Raises:
+            ProjectNotInitializedError: If no initialized project root is found.
+            DatabaseStateError: If the database is inaccessible or corrupted.
+            UnsupportedSchemaVersionError: If the database is at an incompatible schema version.
+        """
+        raw_path = Path(start_path) if start_path is not None else Path.cwd()
+        project_root = self.locator.find_project_root(raw_path)
+        if project_root is None:
+            raise ProjectNotInitializedError()
+
+        db_path = self.locator.get_database_path(project_root)
+        with SQLiteStateStore(db_path, auto_migrate=False) as store:
+            project = store.get_default_project()
+            if project is None:
+                raise ProjectNotInitializedError()
+
+            schema_version = store.get_schema_version()
+            active_id = store.get_active_task_id(project.id)
+
+            active_task_summary: ActiveTaskSummary | None = None
+            if active_id is not None:
+                active_task = store.get_task(active_id)
+                if active_task is not None:
+                    active_task_summary = ActiveTaskSummary(
+                        id=active_task.id,
+                        title=active_task.title,
+                        status=active_task.status,
+                        objective=active_task.objective,
+                        progress=ProgressSummary(
+                            completed=len(active_task.completed_items),
+                            remaining=len(active_task.remaining_items),
+                            issues=len(active_task.known_issues),
+                        ),
+                    )
+
+            state_rel_path = f"{STATE_DIR_NAME}/{DATABASE_FILE_NAME}"
+            return ProjectStatus(
+                project_id=project.id,
+                name=project.name,
+                repo_path=project.repo_path,
+                state_file=state_rel_path,
+                schema_version=schema_version,
+                active_task=active_task_summary,
+            )