pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/session_manager.py

@@ -0,0 +1,365 @@
+"""Production-grade Session Manager for Pulse.
+
+Provides session state management, allowing conversational context, 
+active tasks, and workspace metadata to be persisted and recovered 
+across CLI and VS Code restarts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+SESSION_SCHEMA_VERSION = 1
+
+
+# ---------------------------------------------------------------------------
+# Enums & Data Models
+# ---------------------------------------------------------------------------
+
+
+class SessionStatus(Enum):
+    """Current state of a managed session."""
+
+    ACTIVE = "ACTIVE"
+    ARCHIVED = "ARCHIVED"
+    ERROR = "ERROR"
+
+
+@dataclass(slots=True)
+class SessionTurn:
+    """A single turn in the session's conversation."""
+    
+    role: str
+    content: str
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class SessionEvent:
+    """Structured event emitted for VS Code UI and RPC clients."""
+
+    event_type: str
+    session_id: str
+    status: SessionStatus
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Session:
+    """A persistent unit of conversational and workspace state."""
+
+    id: str
+    title: str = "New Session"
+    status: SessionStatus = SessionStatus.ACTIVE
+    conversation: list[SessionTurn] = field(default_factory=list)
+    active_tasks: list[str] = field(default_factory=list)
+    checkpoints: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize Session object to JSON-compatible dictionary."""
+        return {
+            "schema_version": SESSION_SCHEMA_VERSION,
+            "id": self.id,
+            "title": self.title,
+            "status": self.status.value,
+            "conversation": [asdict(t) for t in self.conversation],
+            "active_tasks": self.active_tasks,
+            "checkpoints": self.checkpoints,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Session:
+        """Deserialize Session object from dictionary."""
+        version = int(data.get("schema_version", 0))
+        if version > SESSION_SCHEMA_VERSION:
+            raise ValueError(
+                f"Session schema v{version} is newer than supported v{SESSION_SCHEMA_VERSION}."
+            )
+        status = SessionStatus(data.get("status", "ACTIVE"))
+        conversation = [
+            SessionTurn(**t) for t in data.get("conversation", []) if isinstance(t, dict)
+        ]
+        
+        return cls(
+            id=data["id"],
+            title=data.get("title", "New Session"),
+            status=status,
+            conversation=conversation,
+            active_tasks=list(data.get("active_tasks", [])),
+            checkpoints=list(data.get("checkpoints", [])),
+            metadata=data.get("metadata", {}),
+            created_at=data.get("created_at", datetime.now(UTC).isoformat()),
+            updated_at=data.get("updated_at", datetime.now(UTC).isoformat()),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Session Store & Event Bus
+# ---------------------------------------------------------------------------
+
+
+class SessionStore:
+    """File-backed persistence store for Sessions."""
+
+    def __init__(self, workspace: Path | None = None) -> None:
+        self.workspace = workspace or Path.cwd()
+        self.store_dir = self.workspace / ".pulse" / "sessions"
+        self.active_session_file = self.store_dir / "active_session.txt"
+        self.store_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_file_path(self, session_id: str) -> Path:
+        return self.store_dir / f"{session_id}.json"
+
+    def save(self, session: Session) -> None:
+        """Persist a session to its JSON file."""
+        temporary_path: Path | None = None
+        try:
+            file_path = self._get_file_path(session.id)
+            temporary_path = file_path.with_name(f".{file_path.name}.{uuid.uuid4().hex}.tmp")
+            with temporary_path.open("w", encoding="utf-8") as f:
+                json.dump(session.to_dict(), f, indent=2)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(temporary_path, file_path)
+        except OSError as err:
+            logger.error(f"Failed to persist session {session.id}: {err}")
+        finally:
+            if temporary_path:
+                temporary_path.unlink(missing_ok=True)
+
+    def load(self, session_id: str) -> Session | None:
+        """Load a session from its JSON file."""
+        file_path = self._get_file_path(session_id)
+        if not file_path.exists():
+            return None
+        try:
+            with file_path.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+            version = int(data.get("schema_version", 0))
+            session = Session.from_dict(data)
+            if version < SESSION_SCHEMA_VERSION:
+                backup = file_path.with_suffix(f".json.schema-v{version}.bak")
+                if not backup.exists():
+                    shutil.copy2(file_path, backup)
+                self.save(session)
+            return session
+        except (OSError, ValueError, json.JSONDecodeError) as err:
+            logger.error(f"Failed to load session {session_id}: {err}")
+            return None
+
+    def list_all(self) -> list[Session]:
+        """List all available sessions."""
+        sessions = []
+        for file_path in self.store_dir.glob("*.json"):
+            session = self.load(file_path.stem)
+            if session:
+                sessions.append(session)
+        return sorted(sessions, key=lambda s: s.updated_at, reverse=True)
+
+    def set_active_session_id(self, session_id: str) -> None:
+        """Mark a session as the currently active one."""
+        try:
+            self.active_session_file.write_text(session_id, encoding="utf-8")
+        except OSError as err:
+            logger.error(f"Failed to write active session: {err}")
+
+    def get_active_session_id(self) -> str | None:
+        """Read the currently active session ID."""
+        if not self.active_session_file.exists():
+            return None
+        try:
+            return self.active_session_file.read_text(encoding="utf-8").strip()
+        except OSError as err:
+            logger.error(f"Failed to read active session: {err}")
+            return None
+
+
+SessionEventListener = Callable[[SessionEvent], Awaitable[None] | None]
+
+
+class SessionEventBus:
+    """Async event bus emitting structured session events."""
+
+    def __init__(self) -> None:
+        self._listeners: list[SessionEventListener] = []
+
+    def subscribe(self, listener: SessionEventListener) -> None:
+        if listener not in self._listeners:
+            self._listeners.append(listener)
+
+    def unsubscribe(self, listener: SessionEventListener) -> None:
+        if listener in self._listeners:
+            self._listeners.remove(listener)
+
+    async def emit(self, event: SessionEvent) -> None:
+        for listener in list(self._listeners):
+            try:
+                res = listener(event)
+                if asyncio.iscoroutine(res) or hasattr(res, "__await__"):
+                    await res
+            # Intentionally broad to isolate execution boundaries and prevent crashes.
+            except Exception as err:  # noqa: BLE001
+                # Intentionally broad to isolate event listener failures from crashing the session manager.
+                logger.warning(f"Error in session event listener: {err}")
+
+
+# ---------------------------------------------------------------------------
+# Session Manager
+# ---------------------------------------------------------------------------
+
+
+class SessionManager:
+    """Principal Session Manager for Pulse.
+
+    Handles session creation, resuming, archiving, event emissions,
+    and coordinates state with the TaskManager.
+    """
+
+    def __init__(
+        self,
+        workspace: Path | None = None,
+        task_manager: Any | None = None,
+        telemetry: Any | None = None,
+    ) -> None:
+        self.workspace = workspace or Path.cwd()
+        self.store = SessionStore(self.workspace)
+        self.event_bus = SessionEventBus()
+        self.task_manager = task_manager
+        self.telemetry = telemetry
+        self._active_session: Session | None = None
+
+    @property
+    def active_session(self) -> Session | None:
+        """Get the currently loaded active session."""
+        return self._active_session
+
+    def _mark_updated(self, session: Session) -> None:
+        session.updated_at = datetime.now(UTC).isoformat()
+        self.store.save(session)
+
+    async def create_session(self, title: str | None = None, make_active: bool = True) -> Session:
+        """Create and optionally activate a new session."""
+        session_id = str(uuid.uuid4())
+        session = Session(
+            id=session_id,
+            title=title or "New Session",
+            status=SessionStatus.ACTIVE
+        )
+        self.store.save(session)
+        
+        if make_active:
+            await self._set_active_session(session)
+
+        if self.telemetry and hasattr(self.telemetry, "log_event"):
+            self.telemetry.log_event("session_created", session_id=session_id)
+
+        await self.event_bus.emit(
+            SessionEvent("session_created", session_id, session.status, payload={"title": session.title})
+        )
+        return session
+
+    async def load_session(self, session_id: str) -> Session:
+        """Load an existing session from store."""
+        session = self.store.load(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found.")
+        return session
+
+    async def resume_session(self, session_id: str) -> Session:
+        """Load a session and mark it as active."""
+        session = await self.load_session(session_id)
+        if session.status == SessionStatus.ARCHIVED:
+            session.status = SessionStatus.ACTIVE
+            self._mark_updated(session)
+
+        await self._set_active_session(session)
+
+        if self.telemetry and hasattr(self.telemetry, "log_event"):
+            self.telemetry.log_event("session_resumed", session_id=session_id)
+
+        await self.event_bus.emit(
+            SessionEvent("session_resumed", session_id, session.status, payload={"title": session.title})
+        )
+        return session
+
+    async def archive_session(self, session_id: str) -> Session:
+        """Archive a session."""
+        session = await self.load_session(session_id)
+        session.status = SessionStatus.ARCHIVED
+        self._mark_updated(session)
+
+        if self._active_session and self._active_session.id == session_id:
+            self._active_session = None
+            try:
+                self.store.active_session_file.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+        if self.telemetry and hasattr(self.telemetry, "log_event"):
+            self.telemetry.log_event("session_archived", session_id=session_id)
+
+        await self.event_bus.emit(
+            SessionEvent("session_archived", session_id, session.status)
+        )
+        return session
+
+    async def get_or_create_active_session(self) -> Session:
+        """Retrieve the last active session, or create a new one if none exists."""
+        if self._active_session:
+            return self._active_session
+
+        active_id = self.store.get_active_session_id()
+        if active_id:
+            try:
+                session = await self.load_session(active_id)
+                if session.status == SessionStatus.ACTIVE:
+                    self._active_session = session
+                    return session
+            except ValueError:
+                pass  # Session file might have been deleted
+
+        # Fallback to creating a new one
+        return await self.create_session(make_active=True)
+
+    async def add_conversation_turn(self, role: str, content: str, session_id: str | None = None, metadata: dict[str, Any] | None = None) -> None:
+        """Append a conversational turn to a session."""
+        if session_id:
+            session = await self.load_session(session_id)
+        else:
+            session = await self.get_or_create_active_session()
+
+        turn = SessionTurn(role=role, content=content, metadata=metadata or {})
+        session.conversation.append(turn)
+        self._mark_updated(session)
+        
+        # If this is the active session, update in-memory reference
+        if self._active_session and self._active_session.id == session.id:
+            self._active_session = session
+
+        await self.event_bus.emit(
+            SessionEvent("session_turn_added", session.id, session.status, payload={"role": role, "length": len(content)})
+        )
+
+    async def _set_active_session(self, session: Session) -> None:
+        self._active_session = session
+        self.store.set_active_session_id(session.id)

pulse/software_engineer.py

@@ -0,0 +1,189 @@
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from enum import Enum
+
+from pulse.context import ContextManager
+from pulse.core.planner import PlanningRequest, RequestPlanner
+from pulse.memory import LongTermMemory
+from pulse.reasoning import IntentCategory, ReasoningEngine
+from pulse.repository import RepositoryIndex
+from pulse.session_manager import SessionManager
+from pulse.streaming import StreamEvent, StreamingExecutionEngine
+from pulse.task_manager import TaskManager
+from pulse.tool_registry import ToolRegistry
+from pulse.verification import VerificationEngine
+
+logger = logging.getLogger(__name__)
+
+
+class EngineerStatus(Enum):
+    IDLE = "IDLE"
+    PLANNING = "PLANNING"
+    EXECUTING = "EXECUTING"
+    VERIFYING = "VERIFYING"
+    BLOCKED = "BLOCKED"
+    COMPLETED = "COMPLETED"
+    CANCELLED = "CANCELLED"
+
+
+@dataclass
+class EngineerEvent:
+    event_type: str  # feature_started, planning_complete, task_started, task_completed, task_failed, feature_blocked, feature_completed
+    message: str
+    metadata: dict[str, str | int | float | bool | None] | None = None
+
+
+@dataclass
+class EngineerResult:
+    status: EngineerStatus
+    tasks_created: int
+    tasks_completed: int
+    summary: str
+
+
+class AutonomousSoftwareEngineer:
+    """Top-level autonomous orchestration engine.
+    
+    Coordinates the Planner, TaskManager, StreamingExecutionEngine, and VerificationEngine
+    to autonomously satisfy complex feature requests.
+    """
+
+    def __init__(
+        self,
+        reasoning_engine: ReasoningEngine,
+        planner: RequestPlanner,
+        task_manager: TaskManager,
+        session_manager: SessionManager,
+        streaming_engine: StreamingExecutionEngine,
+        verification_engine: VerificationEngine,
+        context_manager: ContextManager,
+        memory: LongTermMemory,
+        repository: RepositoryIndex,
+        tool_registry: ToolRegistry,
+    ) -> None:
+        self.reasoning_engine = reasoning_engine
+        self.planner = planner
+        self.task_manager = task_manager
+        self.session_manager = session_manager
+        self.streaming_engine = streaming_engine
+        self.verification_engine = verification_engine
+        self.context_manager = context_manager
+        self.memory = memory
+        self.repository = repository
+        self.tool_registry = tool_registry
+
+    async def execute_feature(
+        self,
+        request: str,
+        session_id: str | None = None,
+        cancellation_token: asyncio.Event | None = None,
+    ) -> AsyncGenerator[EngineerEvent | StreamEvent, None]:
+        """Executes a high-level feature request autonomously."""
+        session = None
+        if session_id:
+            try:
+                session = await self.session_manager.load_session(session_id)
+                await self.session_manager.add_conversation_turn("user", request, session_id=session.id)
+            except ValueError:
+                pass
+        
+        if not session:
+            session = await self.session_manager.get_or_create_active_session()
+            await self.session_manager.add_conversation_turn("user", request, session_id=session.id)
+
+        yield EngineerEvent("feature_started", f"Starting feature: {request[:50]}...", {"session_id": session.id})
+
+        # 1. Reasoning
+        intent_res = await self.reasoning_engine.analyze_intent(request)
+        if intent_res.category == IntentCategory.DIRECT_ANSWER:
+            # Short-circuit for direct answers
+            yield EngineerEvent("feature_completed", "Direct answer provided without planning.")
+            return
+
+        # 2. Planning
+        yield EngineerEvent("planning_started", "Decomposing feature into subtasks...")
+        plan = await self.planner.plan(PlanningRequest(message=request))
+        yield EngineerEvent("planning_complete", f"Generated {len(plan.steps)} subtasks.")
+
+        # 3. Create Tasks
+        created_tasks = []
+        for step in plan.steps:
+            task = await self.task_manager.create_task(
+                title=f"Step {step.id}",
+                goal=step.description
+            )
+            created_tasks.append(task)
+        
+        # 4. Iterative Execution Loop
+        tasks_completed = 0
+        for task in created_tasks:
+            if cancellation_token and cancellation_token.is_set():
+                yield EngineerEvent("feature_cancelled", "Execution cancelled by user.")
+                return
+
+            yield EngineerEvent("task_started", f"Executing task: {task.title}", {"task_id": task.id})
+            
+            # Build context for this step
+            # Execute via StreamingExecutionEngine
+            try:
+                async for stream_event in self.streaming_engine.execute_stream(task.goal, task_id=task.id):
+                    if cancellation_token and cancellation_token.is_set():
+                        await self.task_manager.cancel_task(task.id, reason="User cancelled")
+                        yield EngineerEvent("feature_cancelled", "Execution cancelled by user.")
+                        return
+                    yield stream_event
+
+                await self.task_manager.complete_task(task.id)
+                tasks_completed += 1
+                yield EngineerEvent("task_completed", f"Completed task: {task.title}", {"task_id": task.id})
+            # Intentionally broad to isolate execution boundaries and prevent crashes.
+            except Exception as e:  # noqa: BLE001
+                logger.error(f"Task {task.id} failed: {e}")
+                await self.task_manager.fail_task(task.id, error=str(e))
+                yield EngineerEvent("task_failed", f"Task failed: {task.title} - {e}", {"task_id": task.id})
+                yield EngineerEvent("feature_blocked", "Feature blocked due to task failure.")
+                return
+
+        # 5. Global Verification
+        yield EngineerEvent("verifying", "Running global verification...")
+        try:
+            ver_res = await self.verification_engine.verify()
+            if not ver_res.success:
+                yield EngineerEvent("verification_failed", "Global verification failed.", {"details": ver_res.message})
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"Global verification error: {e}")
+
+        # 6. Completion
+        summary = f"Successfully completed {tasks_completed}/{len(created_tasks)} tasks."
+        await self.session_manager.add_conversation_turn("agent", summary, session_id=session.id)
+        
+        yield EngineerEvent("feature_completed", summary, {"tasks_completed": tasks_completed})
+
+    async def resume_feature(self, session_id: str, cancellation_token: asyncio.Event | None = None) -> AsyncGenerator[EngineerEvent | StreamEvent, None]:
+        """Resumes an interrupted or paused feature session."""
+        try:
+            session = await self.session_manager.resume_session(session_id)
+        except ValueError as e:
+            yield EngineerEvent("resume_failed", str(e))
+            return
+
+        yield EngineerEvent("feature_resumed", f"Resuming session: {session_id}", {"session_id": session.id})
+        
+        # In a real implementation we would fetch pending tasks and execute them.
+        yield EngineerEvent("feature_completed", "Resumed and completed.")
+
+    async def cancel_feature(self, session_id: str) -> None:
+        """Cancels an ongoing feature execution."""
+        # Typically we'd find active tasks for this session and cancel them.
+        try:
+            session = await self.session_manager.load_session(session_id)
+            for task_id in session.active_tasks:
+                try:
+                    await self.task_manager.cancel_task(task_id, reason="Feature cancelled")
+                except ValueError:
+                    pass
+        except ValueError:
+            pass

pulse/storage.py

@@ -0,0 +1,140 @@
+"""Transactional SQLite schema migration, backup, and restore primitives."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sqlite3
+import tempfile
+from collections.abc import Callable
+from contextlib import closing
+from datetime import UTC, datetime
+from pathlib import Path
+
+Migration = Callable[[sqlite3.Connection, int], None]
+
+
+def schema_version(database_path: Path) -> int:
+    if not database_path.exists():
+        return 0
+    with closing(sqlite3.connect(database_path)) as connection:
+        return int(connection.execute("PRAGMA user_version").fetchone()[0])
+
+
+def backup_database(source: Path, destination: Path) -> Path:
+    source = source.resolve()
+    destination = destination.resolve()
+    if not source.is_file():
+        raise FileNotFoundError(source)
+    if source == destination:
+        raise ValueError("Backup destination must differ from the source database.")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with (
+        closing(sqlite3.connect(source)) as source_connection,
+        closing(sqlite3.connect(destination)) as backup_connection,
+    ):
+        source_connection.backup(backup_connection)
+        result = backup_connection.execute("PRAGMA integrity_check").fetchone()
+        if not result or result[0] != "ok":
+            raise sqlite3.DatabaseError("Backup integrity check failed.")
+    return destination
+
+
+def restore_database(backup: Path, destination: Path) -> Path:
+    """Restore a verified backup atomically; the destination must not be in use."""
+    backup = backup.resolve()
+    destination = destination.resolve()
+    if not backup.is_file():
+        raise FileNotFoundError(backup)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    handle, temporary_name = tempfile.mkstemp(
+        prefix=f".{destination.name}.restore-", suffix=".sqlite3", dir=destination.parent
+    )
+    os.close(handle)
+    temporary_path = Path(temporary_name)
+    try:
+        backup_database(backup, temporary_path)
+        for suffix in ("-wal", "-shm"):
+            Path(f"{destination}{suffix}").unlink(missing_ok=True)
+        os.replace(temporary_path, destination)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+    return destination
+
+
+def migrate_database(
+    database_path: Path,
+    target_version: int,
+    migration: Migration,
+    *,
+    timeout: float = 10.0,
+) -> Path | None:
+    """Migrate one database transactionally and back up any existing schema."""
+    if target_version < 1:
+        raise ValueError("Target schema version must be positive.")
+    database_path = database_path.resolve()
+    database_path.parent.mkdir(parents=True, exist_ok=True)
+    backup_path: Path | None = None
+    with closing(
+        sqlite3.connect(database_path, timeout=timeout, isolation_level=None)
+    ) as connection:
+        connection.execute("PRAGMA journal_mode=WAL")
+        current = int(connection.execute("PRAGMA user_version").fetchone()[0])
+        if current > target_version:
+            raise RuntimeError(
+                f"Database schema v{current} is newer than supported v{target_version}."
+            )
+        if current == target_version:
+            return None
+        has_user_tables = connection.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' LIMIT 1"
+        ).fetchone()
+        if has_user_tables:
+            stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+            backup_path = (
+                database_path.parent
+                / "backups"
+                / f"{database_path.stem}.schema-v{current}-to-v{target_version}.{stamp}.sqlite3"
+            )
+            backup_database(database_path, backup_path)
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            migration(connection, current)
+            connection.execute(f"PRAGMA user_version = {target_version}")
+            connection.execute("COMMIT")
+        except BaseException:
+            connection.execute("ROLLBACK")
+            raise
+    return backup_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Inspect, back up, or restore Pulse SQLite state.")
+    commands = parser.add_subparsers(dest="command", required=True)
+    version_parser = commands.add_parser("version")
+    version_parser.add_argument("database", type=Path)
+    backup_parser = commands.add_parser("backup")
+    backup_parser.add_argument("source", type=Path)
+    backup_parser.add_argument("destination", type=Path)
+    restore_parser = commands.add_parser("restore")
+    restore_parser.add_argument("backup", type=Path)
+    restore_parser.add_argument("destination", type=Path)
+    restore_parser.add_argument("--confirm-stopped", action="store_true")
+    args = parser.parse_args()
+    try:
+        if args.command == "version":
+            print(schema_version(args.database))
+        elif args.command == "backup":
+            print(backup_database(args.source, args.destination))
+        else:
+            if not args.confirm_stopped:
+                parser.error("restore requires --confirm-stopped")
+            print(restore_database(args.backup, args.destination))
+    except (OSError, RuntimeError, sqlite3.DatabaseError, ValueError) as exc:
+        print(f"Storage operation failed: {exc}")
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())