cortexshift 0.1.0__py3-none-any.whl

cortexshift/mcp/resources.py

@@ -0,0 +1,45 @@
+"""MCP resource definitions and registration for CortexShift."""
+
+import json
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ResourceError
+
+from cortexshift.domain.errors import CortexShiftError
+from cortexshift.mcp.facade import McpApplicationFacade
+
+
+def register_resources(server: MCPServer, facade: McpApplicationFacade) -> None:
+    """Register read-only MCP resource views backed by McpApplicationFacade."""
+
+    @server.resource("cortexshift://project", mime_type="application/json")
+    def get_project_resource() -> str:
+        """Read-only view of project and bounded task/session summary."""
+        try:
+            return facade.get_project_context().model_dump_json(indent=2)
+        except (CortexShiftError, ValueError) as err:
+            raise ResourceError(f"Failed to read project resource: {err}") from err
+
+    @server.resource("cortexshift://task", mime_type="application/json")
+    def get_task_resource() -> str:
+        """Read-only view of the canonical bound task."""
+        try:
+            return json.dumps(facade.get_current_task(), indent=2)
+        except (CortexShiftError, ValueError) as err:
+            raise ResourceError(f"Failed to read task resource: {err}") from err
+
+    @server.resource("cortexshift://checkpoint/latest", mime_type="application/json")
+    def get_latest_checkpoint_resource() -> str:
+        """Read-only view of the latest checkpoint for the bound task."""
+        try:
+            return facade.get_latest_checkpoint().model_dump_json(indent=2)
+        except (CortexShiftError, ValueError) as err:
+            raise ResourceError(f"Failed to read checkpoint resource: {err}") from err
+
+    @server.resource("cortexshift://repository", mime_type="application/json")
+    def get_repository_resource() -> str:
+        """Read-only view of live Git repository status."""
+        try:
+            return json.dumps(facade.get_repository_status(), indent=2)
+        except (CortexShiftError, ValueError) as err:
+            raise ResourceError(f"Failed to read repository resource: {err}") from err

cortexshift/mcp/server.py

@@ -0,0 +1,52 @@
+"""MCPServer initialization and stdio execution for CortexShift."""
+
+from mcp.server.mcpserver import MCPServer
+
+from cortexshift.adapters.sqlite.store import SQLiteStateStore
+from cortexshift.mcp.context import McpExecutionContext
+from cortexshift.mcp.facade import McpApplicationFacade
+from cortexshift.mcp.resources import register_resources
+from cortexshift.mcp.tools import register_tools
+
+SERVER_NAME = "cortexshift"
+SERVER_TITLE = "CortexShift"
+
+SERVER_INSTRUCTIONS = """\
+CortexShift exposes structured project and task state.
+Use repository files and live Git as the highest authority.
+Use write tools after meaningful milestones to keep canonical Task state current.
+Do not record trivial edits as milestones.
+Checkpoint meaningful engineering decisions and reported test status.
+"""
+
+
+def create_mcp_server(
+    context: McpExecutionContext,
+    store: SQLiteStateStore,
+) -> MCPServer:
+    """Create and configure a CortexShift MCPServer instance for the given context."""
+    server = MCPServer(
+        name=SERVER_NAME,
+        title=SERVER_TITLE,
+        instructions=SERVER_INSTRUCTIONS,
+    )
+
+    facade = McpApplicationFacade(context=context, store=store)
+    register_tools(server=server, facade=facade, context=context)
+    register_resources(server=server, facade=facade)
+
+    return server
+
+
+def run_mcp_server(
+    context: McpExecutionContext,
+    store: SQLiteStateStore,
+) -> None:
+    """Run the CortexShift MCP server over stdio until EOF or process termination.
+
+    Invariants:
+    - Standard output is reserved strictly for the MCP wire protocol.
+    - Diagnostics and logs route exclusively to standard error.
+    """
+    server = create_mcp_server(context=context, store=store)
+    server.run(transport="stdio")

cortexshift/mcp/tools.py

@@ -0,0 +1,176 @@
+"""MCP tool definitions and registration for CortexShift."""
+
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from cortexshift.domain.errors import CortexShiftError
+from cortexshift.mcp.context import McpExecutionContext
+from cortexshift.mcp.facade import McpApplicationFacade
+from cortexshift.mcp.models import (
+    CheckpointResult,
+    CreateCheckpointResult,
+    DecisionResult,
+    ProjectContextResult,
+    TaskMutationResult,
+)
+
+
+def register_tools(
+    server: MCPServer,
+    facade: McpApplicationFacade,
+    context: McpExecutionContext,
+) -> None:
+    """Register read and write MCP tools based on execution context permissions."""
+
+    # -------------------------------------------------------------------------
+    # Read Tools (Always available in both managed and unmanaged contexts)
+    # -------------------------------------------------------------------------
+
+    @server.tool(
+        name="get_project_context",
+        description=(
+            "Get a structured, bounded overview of the current CortexShift project, "
+            "bound task, active session, latest checkpoint, and live repository status."
+        ),
+    )
+    def get_project_context() -> ProjectContextResult:
+        try:
+            return facade.get_project_context()
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to get project context: {err}") from err
+
+    @server.tool(
+        name="get_current_task",
+        description=(
+            "Get the complete canonical task record currently bound to this session, "
+            "including objective, requirements, completed work, remaining work, and known issues."
+        ),
+    )
+    def get_current_task() -> dict[str, Any]:
+        try:
+            return facade.get_current_task()
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to get current task: {err}") from err
+
+    @server.tool(
+        name="get_latest_checkpoint",
+        description=(
+            "Get the latest milestone, session-end, or recovery checkpoint for the bound task. "
+            "Returns null if no checkpoint exists."
+        ),
+    )
+    def get_latest_checkpoint() -> CheckpointResult:
+        try:
+            return facade.get_latest_checkpoint()
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to get latest checkpoint: {err}") from err
+
+    @server.tool(
+        name="get_repository_status",
+        description=(
+            "Inspect live Git repository status (branch, HEAD commit, dirty state, "
+            "staged/unstaged/untracked files, diff shortstat) without modifying state."
+        ),
+    )
+    def get_repository_status() -> dict[str, Any]:
+        try:
+            return facade.get_repository_status()
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to get repository status: {err}") from err
+
+    # -------------------------------------------------------------------------
+    # Write Tools (Registered only for managed, non-read-only sessions)
+    # -------------------------------------------------------------------------
+
+    if not context.can_mutate():
+        return
+
+    @server.tool(
+        name="set_current_work",
+        description=(
+            "Update the description of what the agent is currently working on. "
+            "Pass null or an empty string to clear."
+        ),
+    )
+    def set_current_work(current_work: str | None = None) -> TaskMutationResult:
+        try:
+            return facade.set_current_work(current_work)
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to set current work: {err}") from err
+
+    @server.tool(
+        name="mark_completed",
+        description=(
+            "Record completed work items on the canonical task. "
+            "Deduplicates items, appends to completed, and removes exact matches "
+            "from remaining. Does NOT mark the entire task completed."
+        ),
+    )
+    def mark_completed(items: list[str]) -> TaskMutationResult:
+        try:
+            return facade.mark_completed(items)
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to mark completed: {err}") from err
+
+    @server.tool(
+        name="add_remaining",
+        description=(
+            "Add new remaining work items to the canonical task. "
+            "Deduplicates items and preserves ordering."
+        ),
+    )
+    def add_remaining(items: list[str]) -> TaskMutationResult:
+        try:
+            return facade.add_remaining(items)
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to add remaining items: {err}") from err
+
+    @server.tool(
+        name="record_issue",
+        description=(
+            "Record a known technical issue, blocker, or edge case on the canonical task."
+        ),
+    )
+    def record_issue(items: list[str]) -> TaskMutationResult:
+        try:
+            return facade.record_issue(items)
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to record issue: {err}") from err
+
+    @server.tool(
+        name="record_decision",
+        description=(
+            "Record an important architectural or technical decision. "
+            "Captures an immutable milestone checkpoint containing the decision "
+            "and a live Git working tree snapshot."
+        ),
+    )
+    def record_decision(decision: str) -> DecisionResult:
+        try:
+            return facade.record_decision(decision)
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to record decision: {err}") from err
+
+    @server.tool(
+        name="create_checkpoint",
+        description=(
+            "Create a manual milestone checkpoint for the bound session. "
+            "Captures canonical task state, live Git snapshot, decisions, and "
+            "reported (unverified) test execution status."
+        ),
+    )
+    def create_checkpoint(
+        decisions: list[str] | None = None,
+        test_summary: str | None = None,
+        note: str | None = None,
+    ) -> CreateCheckpointResult:
+        try:
+            return facade.create_checkpoint(
+                decisions=decisions,
+                test_summary=test_summary,
+                note=note,
+            )
+        except (CortexShiftError, ValueError) as err:
+            raise ToolError(f"Failed to create checkpoint: {err}") from err

cortexshift/ports/__init__.py

@@ -0,0 +1,39 @@
+from cortexshift.ports.checkpoint_store import CheckpointStore
+from cortexshift.ports.command_runner import CommandResult, CommandRunner
+from cortexshift.ports.discovery import ProviderDiscoveryPort, ProviderProbe
+from cortexshift.ports.handoff_delivery import (
+    HandoffDeliveryPreparation,
+    HandoffDeliveryStrategy,
+    ProviderHandoffAdapter,
+)
+from cortexshift.ports.handoff_store import HandoffStore
+from cortexshift.ports.headless_runner import HeadlessProviderRunner, HeadlessResult
+from cortexshift.ports.process_runner import InteractiveProcessRunner
+from cortexshift.ports.provider import ProviderAdapter, ProviderRuntimeAdapter
+from cortexshift.ports.repository import RepositoryInspector, RepositorySnapshotStore
+from cortexshift.ports.session_store import SessionStore
+from cortexshift.ports.state_store import StateStore
+from cortexshift.ports.workspace_lease import WorkspaceLease, WorkspaceLeaseManager
+
+__all__ = [
+    "CheckpointStore",
+    "CommandResult",
+    "CommandRunner",
+    "HandoffDeliveryPreparation",
+    "HandoffDeliveryStrategy",
+    "HandoffStore",
+    "HeadlessProviderRunner",
+    "HeadlessResult",
+    "InteractiveProcessRunner",
+    "ProviderAdapter",
+    "ProviderDiscoveryPort",
+    "ProviderHandoffAdapter",
+    "ProviderProbe",
+    "ProviderRuntimeAdapter",
+    "RepositoryInspector",
+    "RepositorySnapshotStore",
+    "SessionStore",
+    "StateStore",
+    "WorkspaceLease",
+    "WorkspaceLeaseManager",
+]

cortexshift/ports/checkpoint_store.py

@@ -0,0 +1,45 @@
+"""Port defining persistence boundaries for canonical CortexShift checkpoints."""
+
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.checkpoint import CheckpointRecord
+
+
+@runtime_checkable
+class CheckpointStore(Protocol):
+    """Abstract port for persisting and querying canonical checkpoint records.
+
+    Kept deliberately narrow and cohesive so the Phase 2 ``StateStore`` interface is not
+    re-expanded. A single concrete adapter may implement several persistence ports.
+    """
+
+    def save_checkpoint(self, checkpoint: CheckpointRecord) -> None:
+        """Persist a canonical CheckpointRecord including its payload."""
+        ...
+
+    def get_checkpoint(self, checkpoint_id: str) -> CheckpointRecord | None:
+        """Retrieve a CheckpointRecord by its stable identifier."""
+        ...
+
+    def list_checkpoints(
+        self,
+        project_id: str | None = None,
+        task_id: str | None = None,
+        limit: int | None = 20,
+    ) -> list[CheckpointRecord]:
+        """List checkpoint records, ordered newest first."""
+        ...
+
+    def get_latest_checkpoint(
+        self,
+        task_id: str,
+    ) -> CheckpointRecord | None:
+        """Retrieve the newest checkpoint record for a given task."""
+        ...
+
+    def list_task_checkpoint_history(
+        self,
+        task_id: str,
+    ) -> list[CheckpointRecord]:
+        """List every checkpoint for one task, oldest first, with deterministic ordering."""
+        ...

cortexshift/ports/command_runner.py

@@ -0,0 +1,56 @@
+"""Port defining the interface for safe external command execution."""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CommandResult(BaseModel):
+    """Result of an executed external command."""
+
+    model_config = ConfigDict(frozen=True)
+
+    command: list[str]
+    exit_code: int
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+    not_found: bool = False
+    error_message: str | None = None
+
+    @property
+    def success(self) -> bool:
+        """Whether the command exited with returncode 0."""
+        return self.exit_code == 0 and not self.timed_out and not self.not_found
+
+
+@runtime_checkable
+class CommandRunner(Protocol):
+    """Abstract port for executing native CLI commands safely.
+
+    Implementations must avoid shell=True, execute commands as argument lists,
+    enforce finite timeouts, and handle process failures gracefully.
+    """
+
+    def run(
+        self,
+        command: list[str],
+        timeout: float = 5.0,
+        env: dict[str, str] | None = None,
+        cwd: Path | str | None = None,
+        sanitize: bool = True,
+    ) -> CommandResult:
+        """Execute a command as an argument list with a finite timeout.
+
+        Args:
+            command: Command and arguments as a list of strings.
+            timeout: Maximum execution duration in seconds.
+            env: Optional environment dictionary override.
+            cwd: Optional working directory for command execution.
+            sanitize: Whether to sanitize, strip ANSI escapes, and bound stdout/stderr.
+
+        Returns:
+            CommandResult containing exit code, stdout, stderr, and failure flags.
+        """
+        ...

cortexshift/ports/discovery.py

@@ -0,0 +1,41 @@
+"""Port defining the interface for discovering and probing AI coding agent providers."""
+
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.doctor import ProviderDiagnostic
+from cortexshift.domain.provider import ProviderId
+
+
+@runtime_checkable
+class ProviderProbe(Protocol):
+    """Abstract port for probing a single provider CLI."""
+
+    @property
+    def provider_id(self) -> ProviderId:
+        """Canonical provider identifier."""
+        ...
+
+    def probe(self) -> ProviderDiagnostic:
+        """Probe the provider CLI and return its diagnostic status."""
+        ...
+
+
+@runtime_checkable
+class ProviderDiscoveryPort(Protocol):
+    """Abstract port for discovering and probing native provider CLIs."""
+
+    def discover_all(self) -> list[ProviderDiagnostic]:
+        """Discover and probe all registered providers."""
+        ...
+
+    def discover_provider(self, provider_id: ProviderId) -> ProviderDiagnostic:
+        """Discover and probe a specific provider by its ID.
+
+        Raises:
+            KeyError: If the provider is not supported/registered.
+        """
+        ...
+
+    def get_supported_provider_ids(self) -> list[ProviderId]:
+        """Return the list of all supported canonical provider IDs."""
+        ...

cortexshift/ports/handoff_delivery.py

@@ -0,0 +1,91 @@
+"""Port defining provider-specific delivery of a canonical handoff context package.
+
+The application core knows only the target provider, the rendered canonical context, and
+the project root. How that context physically reaches a given native CLI (a positional
+initial prompt, or a read-only headless bootstrap followed by a conversation resume) is
+encapsulated entirely behind this port, so orchestration services never branch on
+provider identity.
+"""
+
+from enum import StrEnum
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+from cortexshift.domain.launch import LaunchSpecification
+from cortexshift.domain.provider import ProviderId
+
+
+class HandoffDeliveryStrategy(StrEnum):
+    """Documented native transport used to deliver a handoff to a provider.
+
+    - DIRECT_INITIAL_PROMPT: the canonical context is passed to the provider's native
+      interactive CLI as a single positional initial-prompt argument.
+    - PLAN_BOOTSTRAP_THEN_RESUME: the canonical context is ingested by one read-only
+      headless planning turn, and the resulting native conversation is then resumed
+      interactively.
+    """
+
+    DIRECT_INITIAL_PROMPT = "direct_initial_prompt"
+    READ_ONLY_BOOTSTRAP_THEN_RESUME = "read_only_bootstrap_then_resume"
+    PLAN_BOOTSTRAP_THEN_RESUME = "plan_bootstrap_then_resume"
+
+
+class HandoffDeliveryPreparation(BaseModel):
+    """Outcome of preparing handoff delivery for a target provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    launch_spec: LaunchSpecification
+    native_session_id: str | None = None
+    bootstrap_performed: bool = False
+
+
+@runtime_checkable
+class ProviderHandoffAdapter(Protocol):
+    """Abstract port for delivering canonical handoff context through a native CLI."""
+
+    @property
+    def provider_id(self) -> ProviderId:
+        """Canonical provider identifier."""
+        ...
+
+    @property
+    def display_name(self) -> str:
+        """Human-readable provider name."""
+        ...
+
+    @property
+    def executable(self) -> str:
+        """Base name of the provider CLI executable."""
+        ...
+
+    @property
+    def delivery_strategy(self) -> HandoffDeliveryStrategy:
+        """Documented native transport used by this provider."""
+        ...
+
+    @property
+    def bootstrap_model_turn_required(self) -> bool:
+        """Whether delivery consumes one provider model turn before interactive launch."""
+        ...
+
+    def prepare_delivery(
+        self,
+        executable_path: str,
+        project_root: Path,
+        rendered_context: str,
+        native_session_id: str | None = None,
+    ) -> HandoffDeliveryPreparation:
+        """Deliver the canonical context and return the interactive launch specification.
+
+        Implementations performing a headless bootstrap must parse only the minimum
+        required machine fields and discard the provider response without persisting
+        or logging it.
+
+        Raises:
+            HandoffDeliveryError: If delivery could not be completed. The error carries a
+                safe machine classification and never embeds raw provider output.
+        """
+        ...

cortexshift/ports/handoff_store.py

@@ -0,0 +1,43 @@
+"""Port defining persistence boundaries for canonical CortexShift handoffs."""
+
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.handoff import HandoffFailureCode, HandoffRecord, HandoffStatus
+
+
+@runtime_checkable
+class HandoffStore(Protocol):
+    """Abstract port for persisting and querying canonical handoff records.
+
+    Kept deliberately narrow and cohesive so the Phase 2 ``StateStore`` interface is not
+    re-expanded. A single concrete adapter may implement several persistence ports.
+    """
+
+    def save_handoff(self, handoff: HandoffRecord) -> None:
+        """Persist or update a canonical HandoffRecord including its payload."""
+        ...
+
+    def update_handoff_delivery(
+        self,
+        handoff_id: str,
+        status: HandoffStatus,
+        target_session_id: str | None = None,
+        delivered_at: datetime | None = None,
+        failure_code: HandoffFailureCode | None = None,
+    ) -> None:
+        """Update the delivery metadata of an existing handoff record."""
+        ...
+
+    def get_handoff(self, handoff_id: str) -> HandoffRecord | None:
+        """Retrieve a HandoffRecord by its stable identifier."""
+        ...
+
+    def list_handoffs(
+        self,
+        project_id: str | None = None,
+        task_id: str | None = None,
+        limit: int = 20,
+    ) -> list[HandoffRecord]:
+        """List handoff records, ordered newest first."""
+        ...

cortexshift/ports/headless_runner.py

@@ -0,0 +1,58 @@
+"""Port defining bounded headless execution of a single provider model turn.
+
+Distinct from the short-timeout diagnostic ``CommandRunner`` used by provider discovery:
+a headless provider bootstrap is one full model turn and legitimately needs minutes,
+while still being strictly non-interactive, shell-free, and silent by default.
+"""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+# A single provider planning turn may legitimately take minutes. The bound stays finite
+# so a hung provider can never wedge a CortexShift switch indefinitely.
+DEFAULT_HEADLESS_TIMEOUT_SECONDS = 300.0
+
+
+class HeadlessResult(BaseModel):
+    """Result of a bounded headless provider invocation.
+
+    Captured output is returned to the caller for minimal machine-field parsing only.
+    Adapters must discard it after extracting required metadata and must never persist
+    or log it.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+    not_found: bool = False
+
+
+@runtime_checkable
+class HeadlessProviderRunner(Protocol):
+    """Abstract port for running one non-interactive provider turn without a TTY."""
+
+    def run_headless(
+        self,
+        argv: list[str],
+        cwd: Path | str,
+        timeout: float = DEFAULT_HEADLESS_TIMEOUT_SECONDS,
+        env: dict[str, str] | None = None,
+    ) -> HeadlessResult:
+        """Execute a provider process headlessly, capturing stdout and stderr.
+
+        Args:
+            argv: Argument vector executed directly, never through a shell.
+            cwd: Canonical working directory (the project root).
+            timeout: Finite upper bound appropriate for a single model turn.
+            env: Optional environment overlay.
+
+        Returns:
+            A HeadlessResult describing the outcome. Implementations must not raise
+            on process failure, timeout, or a missing executable.
+        """
+        ...

cortexshift/ports/native_session.py

@@ -0,0 +1,20 @@
+"""Optional exact-resume boundary implemented only by capable runtime adapters."""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from cortexshift.domain.launch import LaunchSpecification
+from cortexshift.domain.native_session import NativeSessionCapabilities
+
+
+@runtime_checkable
+class ProviderNativeSessionAdapter(Protocol):
+    def get_native_capabilities(self) -> NativeSessionCapabilities:
+        """Describe reliable identity and resume mechanisms."""
+        ...
+
+    def build_exact_resume(
+        self, project_root: Path, executable_path: str, native_session_id: str
+    ) -> LaunchSpecification:
+        """Build an exact native resume, without a model turn or process launch."""
+        ...