steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/sessions.py

@@ -0,0 +1,403 @@
+"""Sessions management API client for agent execution sessions."""
+
+from typing import Any, Literal, Self
+
+import httpx
+from loguru import logger
+from pydantic import BaseModel, Field
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from steerdev_agent.api.client import get_api_endpoint, get_api_key
+
+console = Console()
+
+SessionStatus = Literal["pending", "running", "completed", "failed", "cancelled"]
+
+# Status display styles
+STATUS_STYLES: dict[str, str] = {
+    "pending": "dim",
+    "running": "yellow",
+    "completed": "green",
+    "failed": "red",
+    "cancelled": "dim",
+}
+
+
+class SessionCreateRequest(BaseModel):
+    """Request model for creating a session."""
+
+    project_id: str = Field(description="Project ID")
+    task_id: str | None = Field(default=None, description="Task being executed")
+    agent_id: str | None = Field(default=None, description="Existing agent ID to link to")
+    agent_name: str | None = Field(default=None, description="Agent name (creates agent if needed)")
+    agent_type: str = Field(description="Agent type (claude, codex, aider)")
+    prompt: str = Field(description="Initial prompt sent to agent")
+    working_directory: str = Field(description="Working directory for execution")
+    metadata: dict[str, Any] | None = Field(default=None, description="Additional metadata")
+
+
+class SessionResponse(BaseModel):
+    """Response model for session data."""
+
+    id: str
+    project_id: str
+    task_id: str | None = None
+    agent_type: str
+    agent_session_id: str | None = None  # Native session ID for resume
+    status: SessionStatus
+    prompt: str
+    working_directory: str
+    created_at: str
+    updated_at: str
+    metadata: dict[str, Any] | None = None
+
+
+class SessionListResponse(BaseModel):
+    """Response model for listing sessions."""
+
+    sessions: list[SessionResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+class SessionUpdateRequest(BaseModel):
+    """Request model for updating a session."""
+
+    status: SessionStatus | None = None
+    agent_session_id: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class SessionsClient:
+    """Async HTTP client for Sessions API.
+
+    Manages session lifecycle: create, get, update, list.
+    Sessions track agent execution and store the native session ID for resume.
+    """
+
+    def __init__(self, api_key: str | None = None, timeout: float = 30.0) -> None:
+        """Initialize the client.
+
+        Args:
+            api_key: API key for authentication. If not provided, reads from STEERDEV_API_KEY.
+            timeout: Request timeout in seconds.
+        """
+        self.api_key = api_key or get_api_key()
+        self.api_base = get_api_endpoint()
+        self.timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Get request headers with authentication."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create async HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> Self:
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    async def create_session(self, request: SessionCreateRequest) -> SessionResponse | None:
+        """Create a new session.
+
+        Args:
+            request: Session creation request.
+
+        Returns:
+            Created session data or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Creating session at {self.api_base}/sessions")
+
+        try:
+            response = await client.post(
+                f"{self.api_base}/sessions",
+                headers=self.headers,
+                json=request.model_dump(exclude_none=True),
+            )
+
+            if response.status_code == 201:
+                return SessionResponse(**response.json())
+
+            logger.error(f"Failed to create session: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error creating session: {e}")
+            return None
+
+    async def get_session(self, session_id: str) -> SessionResponse | None:
+        """Get a specific session by ID.
+
+        Args:
+            session_id: Session ID (UUID) to fetch.
+
+        Returns:
+            Session data or None if not found.
+        """
+        client = await self._get_client()
+        logger.debug(f"Fetching session {session_id}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/sessions/{session_id}",
+                headers=self.headers,
+            )
+
+            if response.status_code == 200:
+                return SessionResponse(**response.json())
+            if response.status_code == 404:
+                return None
+
+            logger.error(f"Failed to get session: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting session: {e}")
+            return None
+
+    async def update_session(
+        self,
+        session_id: str,
+        status: SessionStatus | None = None,
+        agent_session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SessionResponse | None:
+        """Update a session.
+
+        Args:
+            session_id: Session ID to update.
+            status: New session status.
+            agent_session_id: Native agent session ID for resume.
+            metadata: Additional metadata to merge.
+
+        Returns:
+            Updated session data or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Updating session {session_id}")
+
+        payload: dict[str, Any] = {}
+        if status is not None:
+            payload["status"] = status
+        if agent_session_id is not None:
+            payload["agent_session_id"] = agent_session_id
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        if not payload:
+            logger.warning("No fields to update")
+            return await self.get_session(session_id)
+
+        try:
+            response = await client.patch(
+                f"{self.api_base}/sessions/{session_id}",
+                headers=self.headers,
+                json=payload,
+            )
+
+            if response.status_code == 200:
+                return SessionResponse(**response.json())
+
+            if response.status_code == 404:
+                logger.warning(f"Session {session_id} not found")
+                return None
+
+            logger.error(f"Failed to update session: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error updating session: {e}")
+            return None
+
+    async def list_sessions(
+        self,
+        project_id: str | None = None,
+        task_id: str | None = None,
+        status: SessionStatus | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> SessionListResponse | None:
+        """List sessions with optional filters.
+
+        Args:
+            project_id: Filter by project ID.
+            task_id: Filter by task ID.
+            status: Filter by session status.
+            limit: Maximum number of sessions to return.
+            offset: Offset for pagination.
+
+        Returns:
+            Session list response or None on failure.
+        """
+        client = await self._get_client()
+        params: dict[str, str | int] = {"limit": limit, "offset": offset}
+        if project_id:
+            params["project_id"] = project_id
+        if task_id:
+            params["task_id"] = task_id
+        if status:
+            params["status"] = status
+
+        logger.debug(f"Listing sessions with params: {params}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/sessions",
+                headers=self.headers,
+                params=params,
+            )
+
+            if response.status_code == 200:
+                return SessionListResponse(**response.json())
+
+            logger.error(f"Failed to list sessions: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error listing sessions: {e}")
+            return None
+
+    async def mark_running(self, session_id: str) -> SessionResponse | None:
+        """Mark a session as running.
+
+        Args:
+            session_id: Session ID to update.
+
+        Returns:
+            Updated session data or None on failure.
+        """
+        return await self.update_session(session_id, status="running")
+
+    async def mark_completed(
+        self,
+        session_id: str,
+        agent_session_id: str | None = None,
+    ) -> SessionResponse | None:
+        """Mark a session as completed.
+
+        Args:
+            session_id: Session ID to update.
+            agent_session_id: Native agent session ID for resume.
+
+        Returns:
+            Updated session data or None on failure.
+        """
+        return await self.update_session(
+            session_id,
+            status="completed",
+            agent_session_id=agent_session_id,
+        )
+
+    async def mark_failed(
+        self,
+        session_id: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> SessionResponse | None:
+        """Mark a session as failed.
+
+        Args:
+            session_id: Session ID to update.
+            metadata: Error details to store.
+
+        Returns:
+            Updated session data or None on failure.
+        """
+        return await self.update_session(session_id, status="failed", metadata=metadata)
+
+
+def display_session(session: SessionResponse, title: str = "Session") -> None:
+    """Display a session in a formatted panel.
+
+    Args:
+        session: Session data.
+        title: Panel title.
+    """
+    status_style = STATUS_STYLES.get(session.status, "white")
+
+    session_info = (
+        f"[bold cyan]ID:[/bold cyan] {session.id}\n"
+        f"[bold cyan]Project ID:[/bold cyan] {session.project_id}\n"
+        f"[bold cyan]Agent Type:[/bold cyan] {session.agent_type}\n"
+        f"[bold cyan]Status:[/bold cyan] [{status_style}]{session.status}[/{status_style}]\n"
+        f"[bold cyan]Created:[/bold cyan] {session.created_at}\n"
+    )
+
+    if session.task_id:
+        session_info += f"[bold cyan]Task ID:[/bold cyan] {session.task_id}\n"
+
+    if session.agent_session_id:
+        session_info += f"[bold cyan]Agent Session ID:[/bold cyan] {session.agent_session_id}\n"
+
+    session_info += f"\n[bold cyan]Working Directory:[/bold cyan] {session.working_directory}"
+
+    if session.prompt:
+        # Truncate long prompts
+        prompt_display = (
+            session.prompt[:200] + "..." if len(session.prompt) > 200 else session.prompt
+        )
+        session_info += f"\n\n[bold cyan]Prompt:[/bold cyan]\n{prompt_display}"
+
+    console.print(Panel(session_info, title=title, border_style="green"))
+
+
+def display_session_list(sessions: list[SessionResponse], full_ids: bool = True) -> None:
+    """Display a list of sessions in a formatted table.
+
+    Args:
+        sessions: List of session data.
+        full_ids: If True, show full UUIDs. If False, truncate.
+    """
+    if not sessions:
+        console.print("[yellow]No sessions found[/yellow]")
+        return
+
+    table = Table(title="Sessions")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Agent", style="white")
+    table.add_column("Status", style="magenta")
+    table.add_column("Task ID", style="yellow")
+    table.add_column("Created", style="green")
+
+    for session in sessions:
+        status_style = STATUS_STYLES.get(session.status, "white")
+
+        session_id = session.id
+        task_id = session.task_id or "-"
+        if not full_ids:
+            if len(session_id) > 8:
+                session_id = session_id[:8] + "..."
+            if task_id != "-" and len(task_id) > 8:
+                task_id = task_id[:8] + "..."
+
+        table.add_row(
+            session_id,
+            session.agent_type,
+            f"[{status_style}]{session.status}[/{status_style}]",
+            task_id,
+            session.created_at[:19] if session.created_at else "-",
+        )
+
+    console.print(table)
+    console.print(f"\n[dim]Total: {len(sessions)} sessions[/dim]")