steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/workflow_runs.py

@@ -0,0 +1,351 @@
+"""Workflow runs API client for managing workflow execution."""
+
+from typing import Any, Literal, Self
+
+import httpx
+from loguru import logger
+from pydantic import BaseModel, Field
+
+from steerdev_agent.api.client import get_api_endpoint, get_api_key
+
+WorkflowRunStatus = Literal["pending", "running", "completed", "failed", "cancelled"]
+PhaseRunStatus = Literal["pending", "running", "completed", "failed", "skipped"]
+
+
+class PhaseRunResponse(BaseModel):
+    """Response model for phase run data."""
+
+    id: str
+    workflow_run_id: str
+    phase_id: str
+    phase_name: str
+    phase_type: str
+    status: PhaseRunStatus
+    attempt_number: int = 1
+    input_context: dict[str, Any] = Field(default_factory=dict)
+    output_context: dict[str, Any] = Field(default_factory=dict)
+    result_summary: str | None = None
+    started_at: str | None = None
+    completed_at: str | None = None
+    error_message: str | None = None
+    created_at: str
+    updated_at: str
+
+
+class WorkflowRunResponse(BaseModel):
+    """Response model for workflow run data."""
+
+    id: str
+    workflow_id: str
+    workflow_name: str
+    project_id: str
+    run_id: str | None = None
+    linear_issue_id: str | None = None
+    status: WorkflowRunStatus
+    current_phase_id: str | None = None
+    current_phase_name: str | None = None
+    context: dict[str, Any] = Field(default_factory=dict)
+    phases_completed: int = 0
+    phases_failed: int = 0
+    phases_skipped: int = 0
+    total_phases: int = 0
+    phase_runs: list[PhaseRunResponse] | None = None
+    started_at: str | None = None
+    completed_at: str | None = None
+    error_message: str | None = None
+    created_at: str
+    updated_at: str
+
+
+class WorkflowRunsClient:
+    """Async HTTP client for workflow run lifecycle management.
+
+    Manages the full workflow run lifecycle: start, advance phases,
+    complete/fail phases, and track progress.
+    """
+
+    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 start_workflow(
+        self,
+        workflow_id: str,
+        run_id: str | None = None,
+        linear_issue_id: str | None = None,
+        initial_context: dict[str, Any] | None = None,
+    ) -> WorkflowRunResponse | None:
+        """Start a new workflow run.
+
+        Args:
+            workflow_id: ID of the workflow to execute.
+            run_id: Optional associated agent run ID.
+            linear_issue_id: Optional Linear issue being processed.
+            initial_context: Initial context data for the workflow.
+
+        Returns:
+            Created workflow run or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Starting workflow {workflow_id}")
+
+        payload: dict[str, Any] = {"workflow_id": workflow_id}
+        if run_id:
+            payload["run_id"] = run_id
+        if linear_issue_id:
+            payload["linear_issue_id"] = linear_issue_id
+        if initial_context:
+            payload["initial_context"] = initial_context
+
+        try:
+            response = await client.post(
+                f"{self.api_base}/workflow-runs",
+                headers=self.headers,
+                json=payload,
+            )
+
+            if response.status_code == 201:
+                return WorkflowRunResponse(**response.json())
+
+            logger.error(f"Failed to start workflow: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error starting workflow: {e}")
+            return None
+
+    async def get_workflow_run(
+        self,
+        workflow_run_id: str,
+    ) -> WorkflowRunResponse | None:
+        """Get a specific workflow run by ID.
+
+        Args:
+            workflow_run_id: Workflow run ID to fetch.
+
+        Returns:
+            Workflow run data or None if not found.
+        """
+        client = await self._get_client()
+        logger.debug(f"Fetching workflow run {workflow_run_id}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/workflow-runs/{workflow_run_id}",
+                headers=self.headers,
+            )
+
+            if response.status_code == 200:
+                return WorkflowRunResponse(**response.json())
+            if response.status_code == 404:
+                return None
+
+            logger.error(f"Failed to get workflow run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting workflow run: {e}")
+            return None
+
+    async def advance_phase(
+        self,
+        workflow_run_id: str,
+        output_context: dict[str, Any] | None = None,
+        result_summary: str | None = None,
+    ) -> WorkflowRunResponse | None:
+        """Advance to the next phase after completing the current one.
+
+        Args:
+            workflow_run_id: Workflow run ID to advance.
+            output_context: Context data produced by the current phase.
+            result_summary: Human-readable summary of the phase result.
+
+        Returns:
+            Updated workflow run or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Advancing workflow run {workflow_run_id}")
+
+        payload: dict[str, Any] = {"action": "complete"}
+        if output_context:
+            payload["output_context"] = output_context
+        if result_summary:
+            payload["result_summary"] = result_summary
+
+        try:
+            response = await client.post(
+                f"{self.api_base}/workflow-runs/{workflow_run_id}/advance",
+                headers=self.headers,
+                json=payload,
+            )
+
+            if response.status_code == 200:
+                return WorkflowRunResponse(**response.json())
+
+            logger.error(f"Failed to advance phase: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error advancing phase: {e}")
+            return None
+
+    async def fail_phase(
+        self,
+        workflow_run_id: str,
+        error_message: str,
+    ) -> WorkflowRunResponse | None:
+        """Mark the current phase as failed.
+
+        The workflow engine will handle retries or skip logic based on
+        the phase configuration.
+
+        Args:
+            workflow_run_id: Workflow run ID.
+            error_message: Error message describing the failure.
+
+        Returns:
+            Updated workflow run or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Failing phase for workflow run {workflow_run_id}")
+
+        payload: dict[str, Any] = {
+            "action": "fail",
+            "error_message": error_message,
+        }
+
+        try:
+            response = await client.post(
+                f"{self.api_base}/workflow-runs/{workflow_run_id}/advance",
+                headers=self.headers,
+                json=payload,
+            )
+
+            if response.status_code == 200:
+                return WorkflowRunResponse(**response.json())
+
+            logger.error(f"Failed to fail phase: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error failing phase: {e}")
+            return None
+
+    async def update_phase_run(
+        self,
+        workflow_run_id: str,
+        phase_id: str,
+        status: PhaseRunStatus | None = None,
+        output_context: dict[str, Any] | None = None,
+        result_summary: str | None = None,
+        error_message: str | None = None,
+    ) -> PhaseRunResponse | None:
+        """Update a phase run's status or context.
+
+        Args:
+            workflow_run_id: Workflow run ID.
+            phase_id: Phase ID to update.
+            status: New phase run status.
+            output_context: Updated output context.
+            result_summary: Updated result summary.
+            error_message: Error message if status is failed.
+
+        Returns:
+            Updated phase run or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Updating phase run {phase_id} for workflow run {workflow_run_id}")
+
+        payload: dict[str, Any] = {}
+        if status is not None:
+            payload["status"] = status
+        if output_context is not None:
+            payload["output_context"] = output_context
+        if result_summary is not None:
+            payload["result_summary"] = result_summary
+        if error_message is not None:
+            payload["error_message"] = error_message
+
+        try:
+            response = await client.patch(
+                f"{self.api_base}/workflow-runs/{workflow_run_id}/phases/{phase_id}",
+                headers=self.headers,
+                json=payload,
+            )
+
+            if response.status_code == 200:
+                return PhaseRunResponse(**response.json())
+
+            logger.error(f"Failed to update phase run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error updating phase run: {e}")
+            return None
+
+    async def cancel_workflow_run(
+        self,
+        workflow_run_id: str,
+    ) -> WorkflowRunResponse | None:
+        """Cancel a workflow run.
+
+        Args:
+            workflow_run_id: Workflow run ID to cancel.
+
+        Returns:
+            Updated workflow run or None on failure.
+        """
+        client = await self._get_client()
+        logger.debug(f"Cancelling workflow run {workflow_run_id}")
+
+        try:
+            response = await client.delete(
+                f"{self.api_base}/workflow-runs/{workflow_run_id}",
+                headers=self.headers,
+            )
+
+            if response.status_code == 200:
+                return WorkflowRunResponse(**response.json())
+
+            logger.error(f"Failed to cancel workflow run: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error cancelling workflow run: {e}")
+            return None

steerdev_agent/api/workflows.py

@@ -0,0 +1,191 @@
+"""Workflows API client for fetching workflow definitions."""
+
+from typing import Any, Self
+
+import httpx
+from loguru import logger
+from pydantic import BaseModel, Field
+
+from steerdev_agent.api.client import get_api_endpoint, get_api_key
+
+
+class WorkflowPhaseResponse(BaseModel):
+    """Response model for workflow phase data."""
+
+    id: str
+    workflow_id: str
+    name: str
+    phase_type: str
+    phase_order: int
+    prompt_template: str | None = None
+    is_required: bool = True
+    max_retries: int = 0
+    config_ids: list[str] = Field(default_factory=list)
+    created_at: str
+    updated_at: str
+
+
+class WorkflowResponse(BaseModel):
+    """Response model for workflow data."""
+
+    id: str
+    project_id: str
+    name: str
+    description: str | None = None
+    is_default: bool = False
+    max_retries_per_phase: int = 3
+    phases: list[WorkflowPhaseResponse] = Field(default_factory=list)
+    created_at: str
+    updated_at: str
+
+
+class WorkflowsClient:
+    """Async HTTP client for fetching workflow definitions.
+
+    Workflows define multi-phase task execution patterns.
+    """
+
+    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 get_workflow(self, workflow_id: str) -> WorkflowResponse | None:
+        """Get a workflow by ID.
+
+        Args:
+            workflow_id: Workflow ID to fetch.
+
+        Returns:
+            Workflow data or None if not found.
+        """
+        client = await self._get_client()
+        logger.debug(f"Fetching workflow {workflow_id}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/workflows/{workflow_id}",
+                headers=self.headers,
+            )
+
+            if response.status_code == 200:
+                return WorkflowResponse(**response.json())
+            if response.status_code == 404:
+                logger.warning(f"Workflow not found: {workflow_id}")
+                return None
+
+            logger.error(f"Failed to get workflow: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting workflow: {e}")
+            return None
+
+    async def get_default_workflow(self, project_id: str) -> WorkflowResponse | None:
+        """Get the default workflow for a project.
+
+        Args:
+            project_id: Project ID to get default workflow for.
+
+        Returns:
+            Default workflow or None if not found.
+        """
+        client = await self._get_client()
+        logger.debug(f"Fetching default workflow for project {project_id}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/workflows",
+                headers=self.headers,
+                params={"project_id": project_id, "is_default": "true"},
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                workflows = data.get("workflows", [])
+                if workflows:
+                    return WorkflowResponse(**workflows[0])
+                return None
+
+            logger.error(
+                f"Failed to get default workflow: {response.status_code} - {response.text}"
+            )
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting default workflow: {e}")
+            return None
+
+    async def list_workflows(
+        self,
+        project_id: str | None = None,
+        limit: int = 50,
+    ) -> list[WorkflowResponse]:
+        """List workflows with optional filters.
+
+        Args:
+            project_id: Filter by project ID.
+            limit: Maximum number of workflows to return.
+
+        Returns:
+            List of workflows.
+        """
+        client = await self._get_client()
+        logger.debug("Listing workflows")
+
+        params: dict[str, Any] = {"limit": limit}
+        if project_id:
+            params["project_id"] = project_id
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/workflows",
+                headers=self.headers,
+                params=params,
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                return [WorkflowResponse(**w) for w in data.get("workflows", [])]
+
+            logger.error(f"Failed to list workflows: {response.status_code} - {response.text}")
+            return []
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error listing workflows: {e}")
+            return []