steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/runs.py

@@ -0,0 +1,526 @@
+"""Runs management API client for tracking 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()
+
+RunStatus = Literal["pending", "running", "completed", "failed", "cancelled"]
+
+# Status display styles used by display functions
+STATUS_STYLES: dict[str, str] = {
+    "pending": "dim",
+    "running": "yellow",
+    "completed": "green",
+    "failed": "red",
+    "cancelled": "dim",
+}
+
+
+class RunCreateRequest(BaseModel):
+    """Request model for creating a run."""
+
+    run_id: str = Field(description="Unique run identifier (UUID)")
+    session_name: str = Field(description="Session name for the run")
+    agent_id: str | None = Field(default=None, description="Agent ID executing this run")
+    task_id: str | None = Field(default=None, description="Task being executed")
+    working_directory: str | None = Field(default=None, description="Working directory")
+    application: str | None = Field(
+        default=None, description="Application type (e.g., claude_code)"
+    )
+    initial_prompt: str | None = Field(default=None, description="Initial prompt sent to agent")
+    metadata: dict[str, Any] | None = Field(default=None, description="Additional metadata")
+
+
+class RunResponse(BaseModel):
+    """Response model for run data."""
+
+    id: str
+    session_name: str
+    api_key_id: str | None = None
+    agent_id: str | None = None
+    task_id: str | None = None
+    status: RunStatus
+    working_directory: str | None = None
+    application: str | None = None
+    initial_prompt: str | None = None
+    started_at: str | None = None
+    completed_at: str | None = None
+    duration_seconds: float | None = None
+    tasks_executed: int = 0
+    tasks_succeeded: int = 0
+    tasks_failed: int = 0
+    error_message: str | None = None
+    error_type: str | None = None
+    metadata: dict[str, Any] | None = None
+    last_heartbeat_at: str | None = None
+    # Observability fields
+    current_task_id: str | None = None
+    current_task_title: str | None = None
+    tmux_session: str | None = None
+    tmux_socket: str | None = None
+    agent_host: str | None = None
+    created_at: str
+    updated_at: str
+
+
+class RunListResponse(BaseModel):
+    """Response model for listing runs."""
+
+    runs: list[RunResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+class ActiveRunsResponse(BaseModel):
+    """Response model for active runs."""
+
+    runs: list[RunResponse]
+    count: int
+
+
+class RunsClient:
+    """Async HTTP client for Runs API lifecycle management.
+
+    Manages the full run lifecycle: create, heartbeat, complete, fail.
+    """
+
+    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_run(self, request: RunCreateRequest) -> RunResponse | None:
+        """Create a new run.
+
+        Args:
+            request: Run creation request with run_id and session_name.
+
+        Returns:
+            Created run data or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Creating run {request.run_id} at {self.api_base}/runs")
+
+        try:
+            response = await client.post(
+                f"{self.api_base}/runs",
+                headers=self.headers,
+                json=request.model_dump(exclude_none=True),
+            )
+
+            if response.status_code == 201:
+                return RunResponse(**response.json())
+
+            logger.error(f"Failed to create run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error creating run: {e}")
+            return None
+
+    async def get_run(self, run_id: str) -> RunResponse | None:
+        """Get a specific run by ID.
+
+        Args:
+            run_id: Run ID (UUID) to fetch.
+
+        Returns:
+            Run data or None if not found.
+        """
+        client = await self._get_client()
+        logger.debug(f"Fetching run {run_id}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/runs/{run_id}",
+                headers=self.headers,
+            )
+
+            if response.status_code == 200:
+                return RunResponse(**response.json())
+            if response.status_code == 404:
+                return None
+
+            logger.error(f"Failed to get run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting run: {e}")
+            return None
+
+    async def list_runs(
+        self,
+        status: RunStatus | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> RunListResponse | None:
+        """List runs with optional filters.
+
+        Args:
+            status: Filter by run status.
+            limit: Maximum number of runs to return.
+            offset: Offset for pagination.
+
+        Returns:
+            Run list response or None on failure.
+        """
+        client = await self._get_client()
+        params: dict[str, str | int] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+
+        logger.debug(f"Listing runs with params: {params}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/runs",
+                headers=self.headers,
+                params=params,
+            )
+
+            if response.status_code == 200:
+                return RunListResponse(**response.json())
+
+            logger.error(f"Failed to list runs: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error listing runs: {e}")
+            return None
+
+    async def get_active_runs(self) -> ActiveRunsResponse | None:
+        """Get currently active runs (pending or running).
+
+        Returns:
+            Active runs response or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug("Fetching active runs")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/runs/active",
+                headers=self.headers,
+            )
+
+            if response.status_code == 200:
+                return ActiveRunsResponse(**response.json())
+
+            logger.error(f"Failed to get active runs: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting active runs: {e}")
+            return None
+
+    async def send_heartbeat(
+        self,
+        run_id: str,
+        status: RunStatus | None = None,
+        tasks_executed: int | None = None,
+        tasks_succeeded: int | None = None,
+        tasks_failed: int | None = None,
+        current_task_id: str | None = None,
+        current_task_title: str | None = None,
+        tmux_session: str | None = None,
+        tmux_socket: str | None = None,
+        agent_host: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RunResponse | None:
+        """Send a heartbeat to indicate the run is still alive.
+
+        Args:
+            run_id: Run ID to send heartbeat for.
+            status: Current run status.
+            tasks_executed: Updated tasks executed count.
+            tasks_succeeded: Updated tasks succeeded count.
+            tasks_failed: Updated tasks failed count.
+            current_task_id: ID of the task currently being worked on.
+            current_task_title: Title of the task currently being worked on.
+            tmux_session: Tmux session name for connection.
+            tmux_socket: Tmux socket path for connection.
+            agent_host: Hostname where the agent is running.
+            metadata: Additional metadata to update.
+
+        Returns:
+            Updated run data or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Sending heartbeat for run {run_id}")
+
+        payload: dict[str, Any] = {}
+        if status is not None:
+            payload["status"] = status
+        if tasks_executed is not None:
+            payload["tasks_executed"] = tasks_executed
+        if tasks_succeeded is not None:
+            payload["tasks_succeeded"] = tasks_succeeded
+        if tasks_failed is not None:
+            payload["tasks_failed"] = tasks_failed
+        if current_task_id is not None:
+            payload["current_task_id"] = current_task_id
+        if current_task_title is not None:
+            payload["current_task_title"] = current_task_title
+        if tmux_session is not None:
+            payload["tmux_session"] = tmux_session
+        if tmux_socket is not None:
+            payload["tmux_socket"] = tmux_socket
+        if agent_host is not None:
+            payload["agent_host"] = agent_host
+        if metadata:
+            payload["metadata"] = metadata
+
+        try:
+            response = await client.post(
+                f"{self.api_base}/runs/{run_id}/heartbeat",
+                headers=self.headers,
+                json=payload if payload else None,
+            )
+
+            if response.status_code == 200:
+                return RunResponse(**response.json())
+
+            if response.status_code == 404:
+                logger.warning(f"Run {run_id} not found for heartbeat")
+                return None
+
+            logger.error(f"Failed to send heartbeat: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error sending heartbeat: {e}")
+            return None
+
+    async def complete_run(
+        self,
+        run_id: str,
+        tasks_executed: int | None = None,
+        tasks_succeeded: int | None = None,
+        tasks_failed: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RunResponse | None:
+        """Mark a run as completed.
+
+        Args:
+            run_id: Run ID to complete.
+            tasks_executed: Final tasks executed count.
+            tasks_succeeded: Final tasks succeeded count.
+            tasks_failed: Final tasks failed count.
+            metadata: Additional metadata.
+
+        Returns:
+            Updated run data or None on failure.
+        """
+        client = await self._get_client()
+        logger.info(f"Completing run {run_id}")
+
+        payload: dict[str, Any] = {}
+        if tasks_executed is not None:
+            payload["tasks_executed"] = tasks_executed
+        if tasks_succeeded is not None:
+            payload["tasks_succeeded"] = tasks_succeeded
+        if tasks_failed is not None:
+            payload["tasks_failed"] = tasks_failed
+        if metadata:
+            payload["metadata"] = metadata
+
+        try:
+            response = await client.patch(
+                f"{self.api_base}/runs/{run_id}/complete",
+                headers=self.headers,
+                json=payload if payload else None,
+            )
+
+            if response.status_code == 200:
+                return RunResponse(**response.json())
+
+            if response.status_code == 404:
+                logger.warning(f"Run {run_id} not found for completion")
+                return None
+
+            logger.error(f"Failed to complete run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error completing run: {e}")
+            return None
+
+    async def fail_run(
+        self,
+        run_id: str,
+        error_message: str,
+        error_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RunResponse | None:
+        """Mark a run as failed.
+
+        Args:
+            run_id: Run ID to fail.
+            error_message: Error message describing what went wrong.
+            error_type: Type/category of the error.
+            metadata: Additional metadata.
+
+        Returns:
+            Updated run data or None on failure.
+        """
+        client = await self._get_client()
+        logger.info(f"Failing run {run_id}: {error_message}")
+
+        payload: dict[str, Any] = {"error_message": error_message}
+        if error_type:
+            payload["error_type"] = error_type
+        if metadata:
+            payload["metadata"] = metadata
+
+        try:
+            response = await client.patch(
+                f"{self.api_base}/runs/{run_id}/fail",
+                headers=self.headers,
+                json=payload,
+            )
+
+            if response.status_code == 200:
+                return RunResponse(**response.json())
+
+            if response.status_code == 404:
+                logger.warning(f"Run {run_id} not found for failure")
+                return None
+
+            logger.error(f"Failed to fail run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error failing run: {e}")
+            return None
+
+
+def display_run(run: RunResponse, title: str = "Run") -> None:
+    """Display a run in a formatted panel.
+
+    Args:
+        run: Run data.
+        title: Panel title.
+    """
+    status_style = STATUS_STYLES.get(run.status, "white")
+
+    run_info = (
+        f"[bold cyan]ID:[/bold cyan] {run.id}\n"
+        f"[bold cyan]Session:[/bold cyan] {run.session_name}\n"
+        f"[bold cyan]Status:[/bold cyan] [{status_style}]{run.status}[/{status_style}]\n"
+        f"[bold cyan]Started:[/bold cyan] {run.started_at}\n"
+    )
+
+    if run.completed_at:
+        run_info += f"[bold cyan]Completed:[/bold cyan] {run.completed_at}\n"
+
+    if run.duration_seconds:
+        run_info += f"[bold cyan]Duration:[/bold cyan] {run.duration_seconds:.1f}s\n"
+
+    run_info += (
+        f"\n[bold cyan]Tasks:[/bold cyan] "
+        f"{run.tasks_succeeded}/{run.tasks_executed} succeeded, "
+        f"{run.tasks_failed} failed"
+    )
+
+    if run.agent_id:
+        run_info += f"\n[bold cyan]Agent ID:[/bold cyan] {run.agent_id}"
+
+    if run.application:
+        run_info += f"\n[bold cyan]Application:[/bold cyan] {run.application}"
+
+    if run.error_message:
+        run_info += f"\n\n[bold red]Error:[/bold red] {run.error_message}"
+        if run.error_type:
+            run_info += f" ({run.error_type})"
+
+    if run.last_heartbeat_at:
+        run_info += f"\n[bold cyan]Last Heartbeat:[/bold cyan] {run.last_heartbeat_at}"
+
+    console.print(Panel(run_info, title=title, border_style="green"))
+
+
+def display_run_list(runs: list[RunResponse], full_ids: bool = True) -> None:
+    """Display a list of runs in a formatted table.
+
+    Args:
+        runs: List of run data.
+        full_ids: If True, show full UUIDs. If False, truncate.
+    """
+    if not runs:
+        console.print("[yellow]No runs found[/yellow]")
+        return
+
+    table = Table(title="Runs")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Session", style="white")
+    table.add_column("Status", style="magenta")
+    table.add_column("Tasks", style="yellow")
+    table.add_column("Started", style="green")
+    table.add_column("Duration", style="blue")
+
+    for run in runs:
+        status_style = STATUS_STYLES.get(run.status, "white")
+
+        run_id = run.id
+        if not full_ids and len(run_id) > 8:
+            run_id = run_id[:8] + "..."
+
+        duration = f"{run.duration_seconds:.1f}s" if run.duration_seconds else "-"
+        tasks = f"{run.tasks_succeeded}/{run.tasks_executed}"
+
+        table.add_row(
+            run_id,
+            run.session_name[:30],
+            f"[{status_style}]{run.status}[/{status_style}]",
+            tasks,
+            run.started_at[:19] if run.started_at else "-",
+            duration,
+        )
+
+    console.print(table)
+    console.print(f"\n[dim]Total: {len(runs)} runs[/dim]")