steerdev 0.4.27__py3-none-any.whl

steerdev_agent/executor/__init__.py

@@ -0,0 +1,64 @@
+"""Executor module for running AI agents."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from steerdev_agent.executor.base import AgentExecutor, StreamEvent
+from steerdev_agent.executor.claude import ClaudeExecutor
+from steerdev_agent.executor.stream import StreamParser
+
+if TYPE_CHECKING:
+    from steerdev_agent.config.models import ExecutorConfig
+
+__all__ = [
+    "AgentExecutor",
+    "ClaudeExecutor",
+    "ExecutorFactory",
+    "StreamEvent",
+    "StreamParser",
+]
+
+
+class ExecutorFactory:
+    """Factory for creating agent executors based on configuration."""
+
+    @staticmethod
+    def create(
+        config: ExecutorConfig,
+        working_directory: str,
+        model: str | None = None,
+        max_turns: int | None = None,
+        dry_run: bool = False,
+        worktree_name: str | None = None,
+    ) -> AgentExecutor:
+        """Create an executor based on the configuration.
+
+        Args:
+            config: Executor configuration specifying type and settings.
+            working_directory: Directory to run the agent in.
+            model: Model override (takes precedence over config).
+            max_turns: Maximum number of agent turns.
+            dry_run: If True, print command without executing.
+            worktree_name: Name for Claude CLI --worktree flag.
+
+        Returns:
+            Configured AgentExecutor instance.
+
+        Raises:
+            ValueError: If executor type is not supported.
+        """
+        if config.type == "claude":
+            return ClaudeExecutor(
+                working_directory=working_directory,
+                model=model,
+                max_turns=max_turns,
+                allowed_tools=config.allowed_tools or None,
+                disallowed_tools=config.disallowed_tools or None,
+                mcp_config=config.mcp_config,
+                permission_mode=config.permission_mode,
+                dry_run=dry_run,
+                worktree_name=worktree_name,
+            )
+
+        raise ValueError(f"Unsupported executor type: {config.type}")

steerdev_agent/executor/base.py

@@ -0,0 +1,121 @@
+"""Base executor interface for AI agents."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class EventType(str, Enum):
+    """Types of events emitted by agents."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL_USE = "tool_use"
+    TOOL_RESULT = "tool_result"
+    ERROR = "error"
+    RESULT = "result"
+
+
+@dataclass
+class StreamEvent:
+    """An event from the agent's output stream."""
+
+    event_type: EventType
+    timestamp: datetime
+    data: dict[str, Any]
+    raw_json: str
+
+    @property
+    def is_final(self) -> bool:
+        """Check if this is the final event (result)."""
+        return self.event_type == EventType.RESULT
+
+
+class AgentExecutor(ABC):
+    """Abstract base class for agent executors.
+
+    Executors handle launching and managing CLI agents (Claude Code, Codex, Aider)
+    as subprocesses, streaming their JSON output.
+    """
+
+    def __init__(self, working_directory: str) -> None:
+        """Initialize the executor.
+
+        Args:
+            working_directory: Directory to run the agent in.
+        """
+        self.working_directory = working_directory
+        self._session_id: str | None = None
+
+    @property
+    def session_id(self) -> str | None:
+        """Get the agent's native session ID for resume support."""
+        return self._session_id
+
+    @property
+    @abstractmethod
+    def agent_type(self) -> str:
+        """Return the agent type identifier (e.g., 'claude', 'codex', 'aider')."""
+        ...
+
+    @abstractmethod
+    async def start(self, prompt: str) -> None:
+        """Start the agent with an initial prompt.
+
+        Args:
+            prompt: The initial prompt to send to the agent.
+        """
+        ...
+
+    @abstractmethod
+    async def resume(self, session_id: str, message: str) -> None:
+        """Resume an existing session with a new message.
+
+        Args:
+            session_id: The native session ID to resume.
+            message: The message to continue the conversation with.
+        """
+        ...
+
+    @abstractmethod
+    def stream_events(self) -> AsyncIterator[StreamEvent]:
+        """Stream events from the agent's output.
+
+        Yields:
+            StreamEvent objects as they are parsed from the agent's output.
+        """
+        ...
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the agent process."""
+        ...
+
+    @abstractmethod
+    async def wait(self) -> int:
+        """Wait for the agent process to complete.
+
+        Returns:
+            The exit code of the agent process.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def is_running(self) -> bool:
+        """Check if the agent process is still running."""
+        ...
+
+    async def get_stderr(self) -> str:
+        """Get any stderr output from the agent.
+
+        Override in subclasses that support stderr capture.
+
+        Returns:
+            Stderr output as a string, empty by default.
+        """
+        return ""

steerdev_agent/executor/claude.py

@@ -0,0 +1,328 @@
+"""Claude Code executor implementation."""
+
+import asyncio
+import shutil
+from collections.abc import AsyncIterator
+
+from loguru import logger
+
+from steerdev_agent.executor.base import AgentExecutor, StreamEvent
+from steerdev_agent.executor.stream import StreamParser
+
+
+class ClaudeExecutorError(Exception):
+    """Error during Claude executor operation."""
+
+    pass
+
+
+class ClaudeExecutor(AgentExecutor):
+    """Executor for Claude Code CLI.
+
+    Launches Claude Code as a subprocess with JSON streaming output
+    and manages the process lifecycle.
+    """
+
+    # Claude Code CLI executable name
+    CLAUDE_CLI = "claude"
+
+    def __init__(
+        self,
+        working_directory: str,
+        model: str | None = None,
+        max_turns: int | None = None,
+        allowed_tools: list[str] | None = None,
+        disallowed_tools: list[str] | None = None,
+        mcp_config: str | None = None,
+        permission_mode: str = "dangerously-skip-permissions",
+        dry_run: bool = False,
+        worktree_name: str | None = None,
+    ) -> None:
+        """Initialize the Claude executor.
+
+        Args:
+            working_directory: Directory to run Claude in.
+            model: Model to use (e.g., 'claude-sonnet-4-20250514').
+            max_turns: Maximum number of agent turns.
+            allowed_tools: List of allowed tools.
+            disallowed_tools: List of disallowed tools.
+            mcp_config: Path to MCP config file.
+            permission_mode: Permission mode. Default skips all permissions.
+            dry_run: If True, print the command without executing it.
+            worktree_name: Name for Claude CLI --worktree flag.
+        """
+        super().__init__(working_directory)
+
+        self.model = model
+        self.max_turns = max_turns
+        self.allowed_tools = allowed_tools or []
+        self.disallowed_tools = disallowed_tools or []
+        self.mcp_config = mcp_config
+        self.permission_mode = permission_mode
+        self.dry_run = dry_run
+        self.worktree_name = worktree_name
+
+        self._process: asyncio.subprocess.Process | None = None
+        self._parser = StreamParser()
+        self._dry_run_complete = False
+
+    @property
+    def agent_type(self) -> str:
+        """Return the agent type identifier."""
+        return "claude"
+
+    @property
+    def session_id(self) -> str | None:
+        """Get Claude's session ID from parsed output."""
+        return self._parser.session_id or self._session_id
+
+    def _find_claude_cli(self) -> str:
+        """Find the Claude CLI executable.
+
+        Returns:
+            Path to the Claude CLI.
+
+        Raises:
+            ClaudeExecutorError: If Claude CLI is not found.
+        """
+        claude_path = shutil.which(self.CLAUDE_CLI)
+        if claude_path is None:
+            raise ClaudeExecutorError(
+                f"Claude CLI '{self.CLAUDE_CLI}' not found in PATH. "
+                "Please install Claude Code: https://claude.ai/code"
+            )
+        return claude_path
+
+    def _build_command(self, prompt: str, resume_session: str | None = None) -> list[str]:
+        """Build the Claude CLI command.
+
+        Args:
+            prompt: The prompt or message to send.
+            resume_session: Session ID to resume, if any.
+
+        Returns:
+            Command and arguments as a list.
+        """
+        claude_path = self._find_claude_cli()
+        cmd = [claude_path]
+
+        # Add prompt
+        cmd.extend(["-p", prompt])
+
+        # Output format for streaming (requires --verbose with -p)
+        cmd.extend(["--output-format", "stream-json", "--verbose"])
+
+        # Permission mode
+        if self.permission_mode == "dangerously-skip-permissions":
+            cmd.append("--dangerously-skip-permissions")
+
+        # Resume session if specified
+        if resume_session:
+            cmd.extend(["--resume", resume_session])
+
+        # Model
+        if self.model:
+            cmd.extend(["--model", self.model])
+
+        # Max turns
+        if self.max_turns:
+            cmd.extend(["--max-turns", str(self.max_turns)])
+
+        # Allowed tools
+        for tool in self.allowed_tools:
+            cmd.extend(["--allowedTools", tool])
+
+        # Disallowed tools
+        for tool in self.disallowed_tools:
+            cmd.extend(["--disallowedTools", tool])
+
+        # MCP config
+        if self.mcp_config:
+            cmd.extend(["--mcp-config", self.mcp_config])
+
+        # Worktree isolation
+        if self.worktree_name:
+            cmd.extend(["--worktree", self.worktree_name])
+
+        return cmd
+
+    async def start(self, prompt: str) -> None:
+        """Start Claude with an initial prompt.
+
+        Args:
+            prompt: The initial prompt to send.
+
+        Raises:
+            ClaudeExecutorError: If Claude fails to start.
+        """
+        if self._process is not None and self._process.returncode is None:
+            raise ClaudeExecutorError("Claude is already running")
+
+        cmd = self._build_command(prompt)
+        logger.info(f"Starting Claude in {self.working_directory}")
+        logger.debug(f"Command: {' '.join(cmd)}")
+
+        if self.dry_run:
+            # Print the command that would be executed
+            print("\n[DRY RUN] Would execute command:")
+            print(f"  {' '.join(cmd)}")
+            print(f"\n[DRY RUN] Working directory: {self.working_directory}")
+            print("\n[DRY RUN] Waiting 5 seconds...")
+            await asyncio.sleep(5)
+            print("[DRY RUN] Done.")
+            self._dry_run_complete = True
+            return
+
+        try:
+            self._process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=self.working_directory,
+                limit=10 * 1024 * 1024,  # 10MB buffer for large JSON outputs
+            )
+            logger.info(f"Claude started with PID {self._process.pid}")
+        except OSError as e:
+            raise ClaudeExecutorError(f"Failed to start Claude: {e}") from e
+
+    async def resume(self, session_id: str, message: str) -> None:
+        """Resume an existing Claude session.
+
+        Args:
+            session_id: The Claude session ID to resume.
+            message: The message to continue the conversation with.
+
+        Raises:
+            ClaudeExecutorError: If Claude fails to start.
+        """
+        if self._process is not None and self._process.returncode is None:
+            raise ClaudeExecutorError("Claude is already running")
+
+        self._session_id = session_id
+        cmd = self._build_command(message, resume_session=session_id)
+        logger.info(f"Resuming Claude session {session_id}")
+        logger.debug(f"Command: {' '.join(cmd)}")
+
+        if self.dry_run:
+            # Print the command that would be executed
+            print("\n[DRY RUN] Would execute command:")
+            print(f"  {' '.join(cmd)}")
+            print(f"\n[DRY RUN] Working directory: {self.working_directory}")
+            print("\n[DRY RUN] Waiting 5 seconds...")
+            await asyncio.sleep(5)
+            print("[DRY RUN] Done.")
+            self._dry_run_complete = True
+            return
+
+        try:
+            self._process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=self.working_directory,
+                limit=10 * 1024 * 1024,  # 10MB buffer for large JSON outputs
+            )
+            logger.info(f"Claude resumed with PID {self._process.pid}")
+        except OSError as e:
+            raise ClaudeExecutorError(f"Failed to resume Claude: {e}") from e
+
+    async def stream_events(self) -> AsyncIterator[StreamEvent]:
+        """Stream events from Claude's output.
+
+        Yields:
+            StreamEvent objects parsed from Claude's JSON output.
+
+        Raises:
+            ClaudeExecutorError: If Claude is not running.
+        """
+        # In dry_run mode, there are no events to stream
+        if self.dry_run:
+            return
+
+        if self._process is None or self._process.stdout is None:
+            raise ClaudeExecutorError("Claude is not running")
+
+        async for line_bytes in self._process.stdout:
+            line = line_bytes.decode("utf-8", errors="replace")
+            event = self._parser.parse_line(line)
+            if event is not None:
+                # Update session ID if found
+                if self._parser.session_id:
+                    self._session_id = self._parser.session_id
+                yield event
+
+        # Handle any remaining buffered data
+        final_event = self._parser.flush()
+        if final_event is not None:
+            yield final_event
+
+    async def stop(self) -> None:
+        """Stop the Claude process."""
+        # In dry_run mode, nothing to stop
+        if self.dry_run:
+            self._dry_run_complete = True
+            return
+
+        if self._process is None:
+            return
+
+        if self._process.returncode is not None:
+            logger.debug("Claude process already stopped")
+            return
+
+        logger.info("Stopping Claude process")
+
+        # Try graceful termination first
+        self._process.terminate()
+        try:
+            await asyncio.wait_for(self._process.wait(), timeout=5.0)
+            logger.debug("Claude terminated gracefully")
+        except TimeoutError:
+            logger.warning("Claude did not terminate, killing...")
+            self._process.kill()
+            await self._process.wait()
+            logger.debug("Claude killed")
+
+    async def wait(self) -> int:
+        """Wait for Claude to complete.
+
+        Returns:
+            The exit code of the Claude process.
+
+        Raises:
+            ClaudeExecutorError: If Claude is not running.
+        """
+        # In dry_run mode, return success immediately
+        if self.dry_run:
+            return 0
+
+        if self._process is None:
+            raise ClaudeExecutorError("Claude is not running")
+
+        return await self._process.wait()
+
+    @property
+    def is_running(self) -> bool:
+        """Check if Claude is still running."""
+        # In dry_run mode, it's not actually running
+        if self.dry_run:
+            return not self._dry_run_complete
+        if self._process is None:
+            return False
+        return self._process.returncode is None
+
+    async def get_stderr(self) -> str:
+        """Get any stderr output from Claude.
+
+        Returns:
+            Stderr output as a string.
+        """
+        if self._process is None or self._process.stderr is None:
+            return ""
+
+        try:
+            stderr_bytes = await self._process.stderr.read()
+            return stderr_bytes.decode("utf-8", errors="replace")
+        except Exception as e:
+            logger.warning(f"Failed to read stderr: {e}")
+            return ""

steerdev_agent/executor/stream.py

@@ -0,0 +1,163 @@
+"""JSON stream parser for Claude's stream-json output format."""
+
+import json
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime
+from typing import Any, ClassVar
+
+from loguru import logger
+
+from steerdev_agent.executor.base import EventType, StreamEvent
+
+
+class StreamParser:
+    """Parser for Claude Code's stream-json output format.
+
+    Claude Code outputs newline-delimited JSON when run with --output-format stream-json.
+    Each line is a complete JSON object representing an event.
+    """
+
+    # Event type mapping from Claude's output to our EventType
+    EVENT_TYPE_MAP: ClassVar[dict[str, EventType]] = {
+        "system": EventType.SYSTEM,
+        "user": EventType.USER,
+        "assistant": EventType.ASSISTANT,
+        "tool_use": EventType.TOOL_USE,
+        "tool_result": EventType.TOOL_RESULT,
+        "error": EventType.ERROR,
+        "result": EventType.RESULT,
+    }
+
+    def __init__(self) -> None:
+        """Initialize the parser."""
+        self._buffer = ""
+        self._session_id: str | None = None
+
+    @property
+    def session_id(self) -> str | None:
+        """Get the session ID extracted from the stream."""
+        return self._session_id
+
+    def parse_line(self, line: str) -> StreamEvent | None:
+        """Parse a single JSON line into a StreamEvent.
+
+        Args:
+            line: A single line from the JSON stream.
+
+        Returns:
+            A StreamEvent if parsing succeeded, None otherwise.
+        """
+        line = line.strip()
+        if not line:
+            return None
+
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError as e:
+            logger.warning(f"Failed to parse JSON line: {e}")
+            return None
+
+        # Extract event type
+        event_type_str = data.get("type", "unknown")
+        event_type = self.EVENT_TYPE_MAP.get(event_type_str, EventType.SYSTEM)
+
+        # Extract session ID from result events
+        if event_type == EventType.RESULT:
+            self._extract_session_id(data)
+
+        # Parse timestamp if available, otherwise use now
+        timestamp = self._parse_timestamp(data.get("timestamp"))
+
+        return StreamEvent(
+            event_type=event_type,
+            timestamp=timestamp,
+            data=data,
+            raw_json=line,
+        )
+
+    def _extract_session_id(self, data: dict[str, Any]) -> None:
+        """Extract session ID from result data.
+
+        Args:
+            data: The parsed JSON data.
+        """
+        # Claude stores session ID in result.session_id
+        if "session_id" in data:
+            self._session_id = data["session_id"]
+        elif (
+            "result" in data and isinstance(data["result"], dict) and "session_id" in data["result"]
+        ):
+            self._session_id = data["result"]["session_id"]
+
+    def _parse_timestamp(self, ts: str | None) -> datetime:
+        """Parse a timestamp string or return current time.
+
+        Args:
+            ts: ISO format timestamp string or None.
+
+        Returns:
+            Parsed datetime or current UTC time.
+        """
+        if ts is None:
+            return datetime.now(UTC)
+
+        try:
+            # Handle ISO format with or without Z suffix
+            if ts.endswith("Z"):
+                ts = ts[:-1] + "+00:00"
+            return datetime.fromisoformat(ts)
+        except ValueError:
+            return datetime.now(UTC)
+
+    async def parse_stream(
+        self,
+        lines: AsyncIterator[str],
+    ) -> AsyncIterator[StreamEvent]:
+        """Parse an async stream of lines into events.
+
+        Args:
+            lines: Async iterator of lines from the process output.
+
+        Yields:
+            StreamEvent objects for each valid JSON line.
+        """
+        async for line in lines:
+            event = self.parse_line(line)
+            if event is not None:
+                yield event
+
+    def feed(self, chunk: str) -> list[StreamEvent]:
+        """Feed a chunk of data and return any complete events.
+
+        For use with non-async streams or buffered reading.
+
+        Args:
+            chunk: A chunk of data (may contain partial lines).
+
+        Returns:
+            List of parsed events from complete lines.
+        """
+        self._buffer += chunk
+        events: list[StreamEvent] = []
+
+        while "\n" in self._buffer:
+            line, self._buffer = self._buffer.split("\n", 1)
+            event = self.parse_line(line)
+            if event is not None:
+                events.append(event)
+
+        return events
+
+    def flush(self) -> StreamEvent | None:
+        """Flush any remaining buffered data.
+
+        Call this when the stream ends to handle any partial line.
+
+        Returns:
+            A StreamEvent if there was buffered data, None otherwise.
+        """
+        if self._buffer.strip():
+            event = self.parse_line(self._buffer)
+            self._buffer = ""
+            return event
+        return None

steerdev_agent/git/__init__.py

@@ -0,0 +1 @@
+"""Git module for steerdev."""

steerdev_agent/handlers/__init__.py

@@ -0,0 +1,5 @@
+"""Message handlers for steerdev."""
+
+from steerdev_agent.handlers.prd import PRDHandler
+
+__all__ = ["PRDHandler"]