flowly-code 1.0.0__py3-none-any.whl

flowly_code/agent/tools/dispatch.py

@@ -0,0 +1,840 @@
+"""Dispatch App integration tools.
+
+These tools allow the Flowly agent to interact with Dispatch's
+Rust backend (Axum) via HTTP API, giving access to projects,
+tasks, and Ralph AI workers.
+"""
+
+import json
+from typing import Any
+
+import httpx
+
+from flowly_code.agent.tools.base import Tool
+
+
+class DispatchListProjectsTool(Tool):
+    """List all Dispatch projects."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_list_projects"
+
+    @property
+    def description(self) -> str:
+        return (
+            "List all projects in Dispatch. "
+            "Returns project IDs, names, and creation dates."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        }
+
+    async def execute(self, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(f"{self.base_url}/projects")
+                resp.raise_for_status()
+                body = resp.json()
+                projects = body.get("data", body)
+
+                if not projects:
+                    return "No Dispatch projects found."
+
+                lines = ["Dispatch Projects:"]
+                for p in projects:
+                    name = p.get("name", "Unnamed")
+                    pid = p.get("id", "?")
+                    lines.append(f"  - {name} (id: {pid})")
+                return "\n".join(lines)
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend. Is Dispatch running?"
+        except Exception as e:
+            return f"Error listing projects: {e}"
+
+
+class DispatchGetProjectTool(Tool):
+    """Get detailed info about a single project."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_get_project"
+
+    @property
+    def description(self) -> str:
+        return "Get detailed information about a specific Dispatch project by ID."
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "project_id": {
+                    "type": "string",
+                    "description": "The Dispatch project UUID",
+                },
+            },
+            "required": ["project_id"],
+        }
+
+    async def execute(self, project_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(f"{self.base_url}/projects/{project_id}")
+                resp.raise_for_status()
+                body = resp.json()
+                project = body.get("data", body)
+                return json.dumps(project, indent=2, default=str)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Project not found: {project_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error getting project: {e}"
+
+
+class DispatchListTasksTool(Tool):
+    """List tasks (kanban items) for a project."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_list_tasks"
+
+    @property
+    def description(self) -> str:
+        return (
+            "List tasks in a Dispatch project. "
+            "Shows task title, status, and description. "
+            "IMPORTANT: Use a valid project_id from dispatch_list_projects."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "project_id": {
+                    "type": "string",
+                    "description": "The Dispatch project UUID",
+                },
+            },
+            "required": ["project_id"],
+        }
+
+    async def execute(self, project_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.base_url}/tasks",
+                    params={"project_id": project_id},
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                tasks = body.get("data", body)
+
+                if not tasks:
+                    return f"No tasks found for project {project_id}."
+
+                lines = [f"Tasks for project {project_id}:"]
+                for t in tasks:
+                    status = t.get("status", "unknown")
+                    title = t.get("title", "Untitled")
+                    tid = t.get("id", "?")
+                    desc = t.get("description") or ""
+                    desc_preview = (desc[:80] + "...") if len(desc) > 80 else desc
+                    lines.append(f"  [{status}] {title} (id: {tid})")
+                    if desc_preview:
+                        lines.append(f"    {desc_preview}")
+                return "\n".join(lines)
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error listing tasks: {e}"
+
+
+class DispatchCreateTaskTool(Tool):
+    """Create a new task in a Dispatch project."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_create_task"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Create a new task in a Dispatch project's task board. "
+            "IMPORTANT: You must use a valid project_id from dispatch_list_projects. "
+            "Do NOT guess or make up project IDs."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "project_id": {
+                    "type": "string",
+                    "description": "The Dispatch project UUID",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Task title",
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Task description (markdown supported)",
+                },
+            },
+            "required": ["project_id", "title"],
+        }
+
+    async def execute(
+        self,
+        project_id: str,
+        title: str,
+        description: str = "",
+        **kwargs: Any,
+    ) -> str:
+        try:
+            payload: dict[str, Any] = {
+                "project_id": project_id,
+                "title": title,
+            }
+            if description:
+                payload["description"] = description
+
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.post(
+                    f"{self.base_url}/tasks",
+                    json=payload,
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                task = body.get("data", body)
+                tid = task.get("id", "?")
+                return f"Created task '{title}' (id: {tid}) in project {project_id}."
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error creating task: {e}"
+
+
+class DispatchUpdateTaskTool(Tool):
+    """Update an existing task."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_update_task"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Update an existing task in Dispatch. "
+            "Can change title, description, or status."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "The task UUID to update",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "New title (optional)",
+                },
+                "description": {
+                    "type": "string",
+                    "description": "New description (optional)",
+                },
+                "status": {
+                    "type": "string",
+                    "description": "New status",
+                    "enum": ["open", "in_progress", "in_review", "done", "cancelled"],
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(
+        self,
+        task_id: str,
+        title: str | None = None,
+        description: str | None = None,
+        status: str | None = None,
+        **kwargs: Any,
+    ) -> str:
+        try:
+            payload: dict[str, Any] = {}
+            if title is not None:
+                payload["title"] = title
+            if description is not None:
+                payload["description"] = description
+            if status is not None:
+                payload["status"] = status
+
+            if not payload:
+                return "No fields to update. Provide at least one of: title, description, status."
+
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.put(
+                    f"{self.base_url}/tasks/{task_id}",
+                    json=payload,
+                )
+                resp.raise_for_status()
+                return f"Updated task {task_id}."
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Task not found: {task_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error updating task: {e}"
+
+
+class DispatchRalphStatusTool(Tool):
+    """Check Ralph AI worker status for a task."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_ralph_status"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Check the status of Ralph AI coding workspaces for a task. "
+            "Shows whether workers are running, completed, or failed."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "The task UUID to check Ralph status for",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, task_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.base_url}/tasks/{task_id}/workspaces",
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                workspaces = body.get("data", body)
+
+                if not workspaces:
+                    return f"No Ralph workspaces found for task {task_id}."
+
+                lines = [f"Ralph workspaces for task {task_id}:"]
+                for ws in workspaces:
+                    ws_id = ws.get("id", "?")
+                    status = ws.get("status", "unknown")
+                    lines.append(f"  - Workspace {ws_id}: {status}")
+                return "\n".join(lines)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Task not found: {task_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error checking Ralph status: {e}"
+
+
+class DispatchStartRalphTool(Tool):
+    """Start a Ralph AI coding session for a task."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_start_ralph"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Start a Ralph AI coding session for a project. "
+            "Ralph is an autonomous AI coding agent that works on tasks."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "project_id": {
+                    "type": "string",
+                    "description": "The Dispatch project UUID",
+                },
+            },
+            "required": ["project_id"],
+        }
+
+    async def execute(self, project_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                resp = await client.post(
+                    f"{self.base_url}/projects/{project_id}/ralph/start",
+                )
+                resp.raise_for_status()
+                return f"Ralph session started for project {project_id}."
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Project not found: {project_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error starting Ralph: {e}"
+
+
+class DispatchDeleteTaskTool(Tool):
+    """Delete a task from a Dispatch project."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_delete_task"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Delete a task from Dispatch. "
+            "IMPORTANT: Use a valid task_id from dispatch_list_tasks."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "The task UUID to delete",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, task_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.delete(f"{self.base_url}/tasks/{task_id}")
+                resp.raise_for_status()
+                return f"Deleted task {task_id}."
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Task not found: {task_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error deleting task: {e}"
+
+
+class DispatchGetTaskTool(Tool):
+    """Get detailed info about a single task."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_get_task"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get detailed information about a specific task by ID. "
+            "Returns title, description, status, priority, labels, and more."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "The task UUID",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, task_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(f"{self.base_url}/tasks/{task_id}")
+                resp.raise_for_status()
+                body = resp.json()
+                task = body.get("data", body)
+                return json.dumps(task, indent=2, default=str)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Task not found: {task_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error getting task: {e}"
+
+
+class DispatchListTaskAttemptsTool(Tool):
+    """List task attempts (workspaces) for a task."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_list_task_attempts"
+
+    @property
+    def description(self) -> str:
+        return (
+            "List all task attempts (workspaces) for a task. "
+            "Shows attempt IDs, status, branch names, and executor info. "
+            "Use the attempt ID with dispatch_stop_ralph to stop a running session."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "The task UUID",
+                },
+            },
+            "required": ["task_id"],
+        }
+
+    async def execute(self, task_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.base_url}/task-attempts",
+                    params={"task_id": task_id},
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                attempts = body.get("data", body)
+
+                if not attempts:
+                    return f"No task attempts found for task {task_id}."
+
+                lines = [f"Task attempts for {task_id}:"]
+                for a in attempts:
+                    aid = a.get("id", "?")
+                    status = a.get("status", "unknown")
+                    branch = a.get("branch", "")
+                    lines.append(f"  - {aid}: [{status}] branch: {branch}")
+                return "\n".join(lines)
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error listing task attempts: {e}"
+
+
+class DispatchStartRalphSessionTool(Tool):
+    """Start a Ralph AI coding session on a workspace."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_start_ralph_session"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Start a Ralph AI coding session on a specific task attempt (workspace). "
+            "First use dispatch_list_task_attempts to get the attempt ID. "
+            "Ralph is an autonomous AI coding agent that works on the task."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "attempt_id": {
+                    "type": "string",
+                    "description": "The task attempt (workspace) UUID",
+                },
+            },
+            "required": ["attempt_id"],
+        }
+
+    async def execute(self, attempt_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                resp = await client.post(
+                    f"{self.base_url}/task-attempts/{attempt_id}/ralph/start",
+                )
+                resp.raise_for_status()
+                return f"Ralph session started for workspace {attempt_id}."
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Workspace not found: {attempt_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error starting Ralph session: {e}"
+
+
+class DispatchStopRalphSessionTool(Tool):
+    """Stop a Ralph AI coding session."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_stop_ralph_session"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Stop a running Ralph AI coding session on a task attempt. "
+            "Use dispatch_list_task_attempts to find the attempt ID."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "attempt_id": {
+                    "type": "string",
+                    "description": "The task attempt (workspace) UUID to stop",
+                },
+            },
+            "required": ["attempt_id"],
+        }
+
+    async def execute(self, attempt_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.post(
+                    f"{self.base_url}/task-attempts/{attempt_id}/stop",
+                )
+                resp.raise_for_status()
+                return f"Stopped Ralph session for workspace {attempt_id}."
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Workspace not found: {attempt_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error stopping Ralph session: {e}"
+
+
+class DispatchKanbanSummaryTool(Tool):
+    """Get a kanban board summary for a project."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_kanban_summary"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get a summary of the kanban board for a project. "
+            "Shows task counts grouped by status. "
+            "IMPORTANT: Use a valid project_id from dispatch_list_projects."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "project_id": {
+                    "type": "string",
+                    "description": "The Dispatch project UUID",
+                },
+            },
+            "required": ["project_id"],
+        }
+
+    async def execute(self, project_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.base_url}/tasks",
+                    params={"project_id": project_id},
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                tasks = body.get("data", body)
+
+                if not tasks:
+                    return f"No tasks in project {project_id}."
+
+                # Group by status
+                counts: dict[str, int] = {}
+                for t in tasks:
+                    status = t.get("status", "unknown")
+                    counts[status] = counts.get(status, 0) + 1
+
+                total = len(tasks)
+                lines = [f"Kanban Summary for project {project_id} ({total} tasks):"]
+                for status, count in sorted(counts.items()):
+                    lines.append(f"  {status}: {count}")
+                return "\n".join(lines)
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error getting kanban summary: {e}"
+
+
+class DispatchGetRalphSessionTool(Tool):
+    """Get full Ralph session info including iterations."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_get_ralph_session"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get detailed Ralph session info for a workspace, including all iterations. "
+            "Use dispatch_list_task_attempts to get the attempt ID first."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "attempt_id": {
+                    "type": "string",
+                    "description": "The task attempt (workspace) UUID",
+                },
+            },
+            "required": ["attempt_id"],
+        }
+
+    async def execute(self, attempt_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.base_url}/task-attempts/{attempt_id}/ralph/full",
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                session = body.get("data", body)
+                return json.dumps(session, indent=2, default=str)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"No Ralph session found for workspace {attempt_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error getting Ralph session: {e}"
+
+
+class DispatchGetRalphPrdTool(Tool):
+    """Get Ralph PRD tasks for a project."""
+
+    def __init__(self, port: int = 8080):
+        self.base_url = f"http://127.0.0.1:{port}/api"
+
+    @property
+    def name(self) -> str:
+        return "dispatch_get_ralph_prd"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get Ralph PRD (Product Requirements Document) tasks for a project. "
+            "Shows PRD task details including title, description, and status."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "project_id": {
+                    "type": "string",
+                    "description": "The Dispatch project UUID",
+                },
+            },
+            "required": ["project_id"],
+        }
+
+    async def execute(self, project_id: str, **kwargs: Any) -> str:
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                resp = await client.get(
+                    f"{self.base_url}/projects/{project_id}/ralph/prd",
+                )
+                resp.raise_for_status()
+                body = resp.json()
+                prd_tasks = body.get("data", body)
+
+                if not prd_tasks:
+                    return f"No PRD tasks found for project {project_id}."
+
+                return json.dumps(prd_tasks, indent=2, default=str)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return f"Project not found: {project_id}"
+            return f"Error: {e}"
+        except httpx.ConnectError:
+            return "Error: Cannot connect to Dispatch backend."
+        except Exception as e:
+            return f"Error getting PRD: {e}"