steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/implementation_plan.py

@@ -0,0 +1,408 @@
+"""Implementation Plan parser and display utilities.
+
+Parses and displays structured implementation plans embedded in task descriptions.
+Plans are stored as markdown between <!-- IMPLEMENTATION_PLAN_START --> and
+<!-- IMPLEMENTATION_PLAN_END --> markers.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, BarColumn, TextColumn
+from rich.table import Table
+from rich.tree import Tree
+
+console = Console()
+
+# Plan markers
+PLAN_START_MARKER = "<!-- IMPLEMENTATION_PLAN_START -->"
+PLAN_END_MARKER = "<!-- IMPLEMENTATION_PLAN_END -->"
+
+
+@dataclass
+class FileLocation:
+    """File reference with optional line number."""
+    path: str
+    line_number: int | None = None
+
+    def __str__(self) -> str:
+        if self.line_number:
+            return f"{self.path}:{self.line_number}"
+        return self.path
+
+
+@dataclass
+class PatternReference:
+    """Pattern reference pointing to existing code."""
+    description: str
+    file: str | None = None
+    line_number: int | None = None
+
+
+@dataclass
+class ImplementationStep:
+    """Single implementation step."""
+    order: int
+    description: str
+    completed: bool = False
+    file: FileLocation | None = None
+    pattern: PatternReference | None = None
+
+
+@dataclass
+class FileReference:
+    """File to be modified."""
+    path: str
+    file_type: str = "secondary"  # primary, secondary, test
+    description: str | None = None
+
+
+@dataclass
+class AcceptanceCriterion:
+    """Acceptance criterion."""
+    description: str
+    completed: bool = False
+
+
+@dataclass
+class DependencyReference:
+    """Dependency on another task."""
+    dep_type: str  # blocked_by, blocks, related
+    task_identifier: str
+    title: str | None = None
+
+
+@dataclass
+class ImplementationPlan:
+    """Complete implementation plan."""
+    steps: list[ImplementationStep] = field(default_factory=list)
+    files: list[FileReference] = field(default_factory=list)
+    patterns: list[PatternReference] = field(default_factory=list)
+    acceptance_criteria: list[AcceptanceCriterion] = field(default_factory=list)
+    dependencies: list[DependencyReference] = field(default_factory=list)
+
+    @property
+    def steps_completed(self) -> int:
+        return sum(1 for s in self.steps if s.completed)
+
+    @property
+    def criteria_completed(self) -> int:
+        return sum(1 for c in self.acceptance_criteria if c.completed)
+
+    @property
+    def progress_percentage(self) -> int:
+        total = len(self.steps) + len(self.acceptance_criteria)
+        completed = self.steps_completed + self.criteria_completed
+        return int((completed / total * 100)) if total > 0 else 0
+
+    def is_empty(self) -> bool:
+        return (
+            len(self.steps) == 0 and
+            len(self.files) == 0 and
+            len(self.patterns) == 0 and
+            len(self.acceptance_criteria) == 0 and
+            len(self.dependencies) == 0
+        )
+
+
+def _parse_file_location(text: str) -> FileLocation | None:
+    """Parse file location from text like `src/file.tsx:15`."""
+    match = re.search(r'`([^`]+)`', text)
+    if not match:
+        return None
+
+    parts = match.group(1).split(":")
+    path = parts[0]
+    line_number = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else None
+    return FileLocation(path=path, line_number=line_number)
+
+
+def extract_plan_markdown(description: str) -> str | None:
+    """Extract implementation plan markdown from full description."""
+    start_idx = description.find(PLAN_START_MARKER)
+    end_idx = description.find(PLAN_END_MARKER)
+
+    if start_idx == -1 or end_idx == -1 or start_idx >= end_idx:
+        return None
+
+    return description[start_idx + len(PLAN_START_MARKER):end_idx].strip()
+
+
+def extract_task_description(description: str) -> str:
+    """Extract task description (content before the plan markers)."""
+    start_idx = description.find(PLAN_START_MARKER)
+    if start_idx == -1:
+        return description.strip()
+
+    # Get content before plan, removing trailing separators
+    content = description[:start_idx].strip()
+    content = re.sub(r'\n---\s*$', '', content).strip()
+    return content
+
+
+def _parse_steps(plan_markdown: str) -> list[ImplementationStep]:
+    """Parse steps section from plan markdown."""
+    steps: list[ImplementationStep] = []
+
+    # Find Steps section
+    steps_match = re.search(r'### Steps\s*\n([\s\S]*?)(?=\n### |$)', plan_markdown, re.IGNORECASE)
+    if not steps_match:
+        return steps
+
+    steps_content = steps_match.group(1)
+
+    # Match numbered list items with optional checkboxes
+    # Format: 1. [ ] Description
+    step_pattern = re.compile(r'^\d+\.\s*\[([ xX])\]\s*(.+?)(?=\n\d+\.\s*\[|$)', re.MULTILINE | re.DOTALL)
+
+    for order, match in enumerate(step_pattern.finditer(steps_content)):
+        completed = match.group(1).lower() == 'x'
+        step_block = match.group(2).strip()
+
+        # Extract main description (first line)
+        lines = step_block.split('\n')
+        description = lines[0].strip()
+
+        # Extract file reference
+        file_location = None
+        file_match = re.search(r'- File:\s*`([^`]+)`', step_block, re.IGNORECASE)
+        if file_match:
+            parts = file_match.group(1).split(":")
+            file_location = FileLocation(
+                path=parts[0],
+                line_number=int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else None
+            )
+
+        # Extract pattern reference
+        pattern = None
+        pattern_match = re.search(r'- Pattern:\s*(.+?)(?:\s*\(([^)]+)\))?$', step_block, re.IGNORECASE | re.MULTILINE)
+        if pattern_match:
+            pattern_desc = pattern_match.group(1).strip()
+            pattern_file_loc = _parse_file_location(pattern_desc)
+            pattern = PatternReference(
+                description=re.sub(r'`[^`]+`', '', pattern_desc).strip() or pattern_desc,
+                file=pattern_file_loc.path if pattern_file_loc else None,
+                line_number=pattern_file_loc.line_number if pattern_file_loc else None
+            )
+
+        steps.append(ImplementationStep(
+            order=order,
+            description=description,
+            completed=completed,
+            file=file_location,
+            pattern=pattern
+        ))
+
+    return steps
+
+
+def _parse_files(plan_markdown: str) -> list[FileReference]:
+    """Parse files to modify section."""
+    files: list[FileReference] = []
+
+    files_match = re.search(r'### Files to Modify\s*\n([\s\S]*?)(?=\n### |$)', plan_markdown, re.IGNORECASE)
+    if not files_match:
+        return files
+
+    files_content = files_match.group(1)
+
+    # Match list items like "- `path/to/file.tsx` (primary)"
+    file_pattern = re.compile(r'^-\s*`([^`]+)`(?:\s*\(([^)]+)\))?(?:\s*-\s*(.+))?$', re.MULTILINE)
+
+    for match in file_pattern.finditer(files_content):
+        path = match.group(1)
+        type_hint = (match.group(2) or "").lower()
+        description = match.group(3).strip() if match.group(3) else None
+
+        file_type = "secondary"
+        if "primary" in type_hint or "main" in type_hint:
+            file_type = "primary"
+        elif "test" in type_hint:
+            file_type = "test"
+
+        files.append(FileReference(path=path, file_type=file_type, description=description))
+
+    return files
+
+
+def _parse_patterns(plan_markdown: str) -> list[PatternReference]:
+    """Parse patterns to follow section."""
+    patterns: list[PatternReference] = []
+
+    patterns_match = re.search(r'### Patterns to Follow\s*\n([\s\S]*?)(?=\n### |$)', plan_markdown, re.IGNORECASE)
+    if not patterns_match:
+        return patterns
+
+    patterns_content = patterns_match.group(1)
+
+    # Match list items
+    pattern_re = re.compile(r'^-\s*(.+)$', re.MULTILINE)
+
+    for match in pattern_re.finditer(patterns_content):
+        text = match.group(1).strip()
+        file_location = _parse_file_location(text)
+
+        patterns.append(PatternReference(
+            description=text,
+            file=file_location.path if file_location else None,
+            line_number=file_location.line_number if file_location else None
+        ))
+
+    return patterns
+
+
+def _parse_acceptance_criteria(plan_markdown: str) -> list[AcceptanceCriterion]:
+    """Parse acceptance criteria section."""
+    criteria: list[AcceptanceCriterion] = []
+
+    criteria_match = re.search(r'### Acceptance Criteria\s*\n([\s\S]*?)(?=\n### |$)', plan_markdown, re.IGNORECASE)
+    if not criteria_match:
+        return criteria
+
+    criteria_content = criteria_match.group(1)
+
+    # Match checkbox items
+    criterion_pattern = re.compile(r'^-\s*\[([ xX])\]\s*(.+)$', re.MULTILINE)
+
+    for match in criterion_pattern.finditer(criteria_content):
+        criteria.append(AcceptanceCriterion(
+            completed=match.group(1).lower() == 'x',
+            description=match.group(2).strip()
+        ))
+
+    return criteria
+
+
+def _parse_dependencies(plan_markdown: str) -> list[DependencyReference]:
+    """Parse dependencies section."""
+    dependencies: list[DependencyReference] = []
+
+    deps_match = re.search(r'### Dependencies\s*\n([\s\S]*?)(?=\n### |$)', plan_markdown, re.IGNORECASE)
+    if not deps_match:
+        return dependencies
+
+    deps_content = deps_match.group(1)
+
+    # Match "- Blocked by: TASK-123" or "- Blocks: TASK-456 (Some title)"
+    dep_pattern = re.compile(r'^-\s*(Blocked by|Blocks|Related to):\s*([A-Z]+-\d+)(?:\s*\(([^)]+)\))?', re.IGNORECASE | re.MULTILINE)
+
+    for match in dep_pattern.finditer(deps_content):
+        type_text = match.group(1).lower()
+        dep_type = "related"
+        if type_text == "blocked by":
+            dep_type = "blocked_by"
+        elif type_text == "blocks":
+            dep_type = "blocks"
+
+        dependencies.append(DependencyReference(
+            dep_type=dep_type,
+            task_identifier=match.group(2),
+            title=match.group(3).strip() if match.group(3) else None
+        ))
+
+    return dependencies
+
+
+def parse_implementation_plan(description: str | None) -> ImplementationPlan | None:
+    """Parse implementation plan from task description.
+
+    Args:
+        description: Full task description/prompt that may contain an implementation plan.
+
+    Returns:
+        Parsed ImplementationPlan or None if no plan found.
+    """
+    if not description:
+        return None
+
+    plan_markdown = extract_plan_markdown(description)
+    if not plan_markdown:
+        return None
+
+    return ImplementationPlan(
+        steps=_parse_steps(plan_markdown),
+        files=_parse_files(plan_markdown),
+        patterns=_parse_patterns(plan_markdown),
+        acceptance_criteria=_parse_acceptance_criteria(plan_markdown),
+        dependencies=_parse_dependencies(plan_markdown)
+    )
+
+
+def display_implementation_plan(plan: ImplementationPlan) -> None:
+    """Display implementation plan using rich formatting.
+
+    Args:
+        plan: Parsed implementation plan to display.
+    """
+    if plan.is_empty():
+        return
+
+    # Header with progress
+    progress_text = f"{plan.steps_completed}/{len(plan.steps)} steps"
+    if plan.acceptance_criteria:
+        progress_text += f", {plan.criteria_completed}/{len(plan.acceptance_criteria)} criteria"
+    progress_text += f" ({plan.progress_percentage}%)"
+
+    console.print(f"\n[bold blue]Implementation Plan[/bold blue] - {progress_text}")
+    console.print("─" * 60)
+
+    # Steps
+    if plan.steps:
+        console.print("\n[bold cyan]Steps:[/bold cyan]")
+        for step in plan.steps:
+            checkbox = "✓" if step.completed else "○"
+            style = "dim strikethrough" if step.completed else ""
+            console.print(f"  [{checkbox}] [{style}]{step.order + 1}. {step.description}[/{style}]")
+
+            if step.file:
+                console.print(f"      [dim]File: {step.file}[/dim]")
+            if step.pattern:
+                pattern_text = step.pattern.description
+                if step.pattern.file:
+                    loc = FileLocation(step.pattern.file, step.pattern.line_number)
+                    pattern_text += f" ({loc})"
+                console.print(f"      [dim]Pattern: {pattern_text}[/dim]")
+
+    # Files
+    if plan.files:
+        console.print("\n[bold cyan]Files to Modify:[/bold cyan]")
+        for f in plan.files:
+            type_badge = f"[{f.file_type}]" if f.file_type != "secondary" else ""
+            desc = f" - {f.description}" if f.description else ""
+            console.print(f"  • {f.path} {type_badge}{desc}")
+
+    # Patterns
+    if plan.patterns:
+        console.print("\n[bold cyan]Patterns to Follow:[/bold cyan]")
+        for p in plan.patterns:
+            loc_text = ""
+            if p.file:
+                loc = FileLocation(p.file, p.line_number)
+                loc_text = f" ({loc})"
+            console.print(f"  • {p.description}{loc_text}")
+
+    # Acceptance Criteria
+    if plan.acceptance_criteria:
+        console.print("\n[bold cyan]Acceptance Criteria:[/bold cyan]")
+        for c in plan.acceptance_criteria:
+            checkbox = "✓" if c.completed else "○"
+            style = "dim strikethrough" if c.completed else ""
+            console.print(f"  [{checkbox}] [{style}]{c.description}[/{style}]")
+
+    # Dependencies
+    if plan.dependencies:
+        console.print("\n[bold cyan]Dependencies:[/bold cyan]")
+        for d in plan.dependencies:
+            type_labels = {
+                "blocked_by": "[red]Blocked by[/red]",
+                "blocks": "[yellow]Blocks[/yellow]",
+                "related": "[dim]Related to[/dim]"
+            }
+            label = type_labels.get(d.dep_type, d.dep_type)
+            title_text = f" ({d.title})" if d.title else ""
+            console.print(f"  • {label}: {d.task_identifier}{title_text}")
+
+    console.print()

steerdev_agent/api/messages.py

@@ -0,0 +1,231 @@
+"""Message API client for agent-to-user communication."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID  # noqa: TC003 - Required at runtime by Pydantic
+
+import httpx
+from loguru import logger
+from pydantic import BaseModel
+
+from steerdev_agent.api.client import get_api_endpoint, get_api_key
+
+
+class AgentMessage(BaseModel):
+    """Message from user to agent."""
+
+    id: UUID
+    content: str
+    message_type: str  # inject_stdin, agent_handle
+    status: str
+    run_id: UUID | None = None
+    user_id: str
+    created_at: str
+    expires_at: str
+
+
+class MessageClientError(Exception):
+    """Error communicating with the messages API."""
+
+    pass
+
+
+class MessageClient:
+    """Async client for polling and acknowledging user messages.
+
+    This client allows agents to:
+    - Poll for pending messages from users
+    - Acknowledge message receipt
+    - Respond to messages (for agent_handle type)
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        api_key: str | None = None,
+        api_endpoint: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the message client.
+
+        Args:
+            agent_id: The agent ID to poll messages for.
+            api_key: API key for authentication.
+            api_endpoint: Base API endpoint.
+            timeout: Request timeout in seconds.
+        """
+        self.agent_id = agent_id
+        self._api_key = api_key or get_api_key()
+        self._api_endpoint = api_endpoint or get_api_endpoint()
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            headers = {
+                "Content-Type": "application/json",
+                "User-Agent": "steerdev/0.1.0",
+            }
+            if self._api_key:
+                headers["Authorization"] = f"Bearer {self._api_key}"
+
+            self._client = httpx.AsyncClient(
+                headers=headers,
+                timeout=httpx.Timeout(self._timeout),
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def poll_messages(
+        self,
+        run_id: str | None = None,
+        since: str | None = None,
+        limit: int = 10,
+    ) -> list[AgentMessage]:
+        """Poll for pending messages from users.
+
+        Args:
+            run_id: Optional run ID to filter messages.
+            since: Optional ISO timestamp to get messages after.
+            limit: Maximum number of messages to return.
+
+        Returns:
+            List of pending messages.
+        """
+        if not self._api_key:
+            logger.warning("No API key configured, skipping message poll")
+            return []
+
+        try:
+            client = await self._get_client()
+
+            params: dict[str, Any] = {
+                "status": "pending",
+                "limit": limit,
+            }
+            if run_id:
+                params["run_id"] = run_id
+            if since:
+                params["since"] = since
+
+            url = f"{self._api_endpoint}/agents/{self.agent_id}/messages"
+            response = await client.get(url, params=params)
+
+            if response.status_code == 200:
+                data = response.json()
+                messages = [AgentMessage(**msg) for msg in data.get("messages", [])]
+                if messages:
+                    logger.debug(f"Received {len(messages)} pending messages")
+                return messages
+            elif response.status_code == 404:
+                logger.warning(f"Agent {self.agent_id} not found")
+                return []
+            else:
+                logger.error(f"Failed to poll messages: {response.status_code} - {response.text}")
+                return []
+
+        except httpx.TimeoutException:
+            logger.warning("Timeout polling for messages")
+            return []
+        except httpx.HTTPError as e:
+            logger.error(f"HTTP error polling messages: {e}")
+            return []
+        except Exception as e:
+            logger.exception(f"Unexpected error polling messages: {e}")
+            return []
+
+    async def acknowledge_message(
+        self,
+        message_id: str | UUID,
+        status: str = "acknowledged",
+        response: str | None = None,
+    ) -> bool:
+        """Acknowledge receipt of a message.
+
+        Args:
+            message_id: The message ID to acknowledge.
+            status: The new status ("delivered" or "acknowledged").
+            response: Optional response text for agent_handle messages.
+
+        Returns:
+            True if acknowledged successfully.
+        """
+        if not self._api_key:
+            logger.warning("No API key configured, skipping message acknowledge")
+            return False
+
+        try:
+            client = await self._get_client()
+
+            payload: dict[str, Any] = {"status": status}
+            if response:
+                payload["response"] = response
+
+            url = f"{self._api_endpoint}/agents/{self.agent_id}/messages/{message_id}"
+            http_response = await client.patch(url, json=payload)
+
+            if http_response.status_code == 200:
+                logger.debug(f"Acknowledged message {message_id}")
+                return True
+            else:
+                logger.error(
+                    f"Failed to acknowledge message: {http_response.status_code} - {http_response.text}"
+                )
+                return False
+
+        except httpx.TimeoutException:
+            logger.warning("Timeout acknowledging message")
+            return False
+        except httpx.HTTPError as e:
+            logger.error(f"HTTP error acknowledging message: {e}")
+            return False
+        except Exception as e:
+            logger.exception(f"Unexpected error acknowledging message: {e}")
+            return False
+
+    async def mark_delivered(self, message_id: str | UUID) -> bool:
+        """Mark a message as delivered (received by agent).
+
+        Args:
+            message_id: The message ID.
+
+        Returns:
+            True if marked successfully.
+        """
+        return await self.acknowledge_message(message_id, status="delivered")
+
+    async def mark_acknowledged(
+        self,
+        message_id: str | UUID,
+        response: str | None = None,
+    ) -> bool:
+        """Mark a message as acknowledged (processed by agent).
+
+        Args:
+            message_id: The message ID.
+            response: Optional response for agent_handle messages.
+
+        Returns:
+            True if marked successfully.
+        """
+        return await self.acknowledge_message(message_id, status="acknowledged", response=response)
+
+    async def __aenter__(self) -> MessageClient:
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit async context manager."""
+        await self.close()