Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

22.5 KB
Raw Blame
from typing import Any

from django.db import transaction

from asgiref.sync import async_to_sync, sync_to_async
from pydantic import BaseModel, Field

from posthog.egress.limiter.policies import Priority
from posthog.integrations import IntegrationManager
from posthog.storage import object_storage

from ee.hogai.tool import MaxTool

from .facade import api as tasks_facade
from .facade.access import analytics_context_reader
from .logic.services.workflow_dispatch import WorkflowDispatchOptions, enqueue_or_start_workflow
from .models import Task, TaskRun
from .task_profiles import USER
from .temporal.client import execute_task_processing_workflow_async
from .visibility import task_control_q, task_visibility_q


class CreateTaskArgs(BaseModel):
    title: str = Field(description="Title of the task")
    description: str = Field(description="Detailed description of what the task should accomplish")
    repository: str = Field(description="Repository in format 'org/repo' (e.g., 'posthog/posthog-js')")
    run: bool = Field(default=True, description="Whether to immediately run the task after creation")


class RunTaskArgs(BaseModel):
    task_id: str = Field(description="UUID of the task to run")


class GetTaskRunArgs(BaseModel):
    task_id: str = Field(description="UUID of the task")
    run_id: str | None = Field(default=None, description="UUID of a specific run. If not provided, uses the latest run")


class GetTaskRunLogsArgs(BaseModel):
    task_id: str = Field(description="UUID of the task")
    run_id: str | None = Field(default=None, description="UUID of a specific run. If not provided, uses the latest run")


class ListTasksArgs(BaseModel):
    origin_product: str | None = Field(
        default=None, description="Filter by origin product (e.g., 'error_tracking', 'user_created')"
    )
    repository: str | None = Field(default=None, description="Filter by repository (e.g., 'posthog/posthog-js')")
    limit: int = Field(default=10, ge=1, le=50, description="Maximum number of tasks to return")


class ListTaskRunsArgs(BaseModel):
    task_id: str = Field(description="UUID of the task to list runs for")
    limit: int = Field(default=10, ge=1, le=50, description="Maximum number of runs to return")


class ListRepositoriesArgs(BaseModel):
    search: str | None = Field(default=None, description="Optional search term to filter repositories by name")


class CreateTaskTool(MaxTool):
    name: str = "create_task"
    description: str = """
Create a new task in the Tasks product.

Use this tool when the user wants to:
- Create a new coding task for an AI agent to execute
- Set up a task to fix an issue, implement a feature, or make changes to a repository

By default, the task will be created and immediately executed. Set run=false to create without executing.
    """.strip()
    args_schema: type[BaseModel] = CreateTaskArgs

    async def _arun_impl(
        self, title: str, description: str, repository: str, run: bool = True
    ) -> tuple[str, dict[str, Any]]:
        slack_thread_context = (self._config.get("configurable") or {}).get("slack_thread_context")

        @sync_to_async
        @transaction.atomic
        def create_task_and_maybe_run():
            github_integration = IntegrationManager.github.oauth.find(self._team.id)

            task = Task.objects.create(
                team=self._team,
                created_by=self._user,
                channel_id=tasks_facade.ensure_personal_channel_id(self._team.id, self._user.id),
                title=title,
                description=description,
                origin_product=Task.OriginProduct.USER_CREATED,
                profile=USER.key,
                repository=repository,
                github_integration_id=github_integration.id if github_integration is not None else None,
            )

            task_run = None
            if run:
                task_run = task.create_run()
                enqueue_or_start_workflow(
                    task_run,
                    start_workflow=lambda **kwargs: async_to_sync(execute_task_processing_workflow_async)(**kwargs),
                    options=WorkflowDispatchOptions(user_id=self._user.id, slack_thread_context=slack_thread_context),
                )

            task_url = f"/project/{self._team.project.id}/tasks/{task.id}"
            if task_run:
                task_url = f"{task_url}?runId={task_run.id}"

            result = {
                "task_id": str(task.id),
                "slug": task.slug,
                "title": task.title,
                "url": task_url,
                "team_id": task.team.id,
            }

            if task_run:
                result["latest_run"] = {
                    "run_id": str(task_run.id),
                    "status": task_run.status,
                    "status_display": task_run.get_status_display(),
                }

            return result

        result = await create_task_and_maybe_run()

        if run and "latest_run" in result:
            return (
                f"Created and started task '{result['title']}' (ID: {result['task_id']}).\n"
                f"Run ID: {result['latest_run']['run_id']}\n"
                f"View at {result['url']}",
                result,
            )

        return (
            f"Created task '{result['title']}' (ID: {result['task_id']}). "
            f"Use the run_task tool to execute it. View at {result['url']}",
            result,
        )


class RunTaskTool(MaxTool):
    name: str = "run_task"
    description: str = """
Trigger execution of an existing task.

Use this tool when the user wants to:
- Start a task that was previously created
- Re-run a task after it failed or was cancelled
- Execute a task to make changes to a repository
    """.strip()
    args_schema: type[BaseModel] = RunTaskArgs

    async def _arun_impl(self, task_id: str) -> tuple[str, dict[str, Any]]:
        slack_thread_context = (self._config.get("configurable") or {}).get("slack_thread_context")

        @sync_to_async
        @transaction.atomic
        def get_task_and_create_run():
            task = (
                Task.objects.select_for_update(of=("self",))
                .filter(id=task_id, team=self._team, deleted=False)
                .filter(task_control_q(self._user.id))
                .first()
            )

            if not task:
                return None
            if task.runtime == Task.Runtime.PI:
                return {"error": "unsupported_runtime"}

            task_run = task.create_run()
            enqueue_or_start_workflow(
                task_run,
                start_workflow=lambda **kwargs: async_to_sync(execute_task_processing_workflow_async)(**kwargs),
                options=WorkflowDispatchOptions(user_id=self._user.id, slack_thread_context=slack_thread_context),
            )
            task_url = f"/project/{task.team.project.id}/tasks/{task.id}?runId={task_run.id}"
            return {
                "task_id": str(task.id),
                "run_id": str(task_run.id),
                "slug": task.slug,
                "title": task.title,
                "team_id": task.team.id,
                "url": task_url,
            }

        result = await get_task_and_create_run()

        if not result:
            return f"Task with ID {task_id} not found", {"error": "not_found"}
        if result.get("error") == "unsupported_runtime":
            return "Pi tasks cannot be run through the ACP task workflow.", result

        return (
            f"Started execution of task '{result['title']}' ({result['slug']}).\n"
            f"Run ID: {result['run_id']}\n"
            f"View at {result['url']}",
            result,
        )


class GetTaskRunTool(MaxTool):
    name: str = "get_task_run"
    description: str = """
Get the current status of a task run, including stage, status, branch, and any errors.

Use this tool when the user wants to:
- Check if a task is still running
- See if a task completed successfully or failed
- Get the current stage of a task execution (research, plan, build, etc.)
    """.strip()
    args_schema: type[BaseModel] = GetTaskRunArgs

    async def _arun_impl(self, task_id: str, run_id: str | None = None) -> tuple[str, dict[str, Any]]:
        may_read = analytics_context_reader(team_id=self._team.id, user_id=self._user.id)

        @sync_to_async
        def get_task_and_run():
            task = (
                Task.objects.filter(id=task_id, team=self._team, deleted=False)
                .filter(task_visibility_q(self._user.id))
                .first()
            )

            if not task:
                return {"error": "not_found", "task_id": task_id}

            if run_id:
                task_run = TaskRun.objects.filter(id=run_id, task=task).first()
            else:
                task_run = task.latest_run

            task_info = {
                "id": str(task.id),
                "slug": task.slug,
                "title": task.title,
                "repository": task.repository,
            }

            if not task_run:
                return {"error": "no_runs" if not run_id else "run_not_found", "task_info": task_info, "run_id": run_id}

            if "analytics_query_context" in (task_run.state or {}) and not may_read(
                task_run.state["analytics_query_context"]
            ):
                return {"error": "permission_denied"}

            return {
                "task_info": task_info,
                "run": {
                    "run_id": str(task_run.id),
                    "status": task_run.status,
                    "status_display": task_run.get_status_display(),
                    "stage": task_run.stage,
                    "branch": task_run.branch,
                    "created_at": task_run.created_at.isoformat(),
                    "completed_at": task_run.completed_at.isoformat() if task_run.completed_at else None,
                    "error_message": task_run.error_message,
                    "output": task_run.output,
                },
            }

        result = await get_task_and_run()

        if result.get("error") == "permission_denied":
            return "You do not have access to the analytics data in this run.", result

        if result.get("error") == "not_found":
            return f"Task with ID {task_id} not found", {"error": "not_found"}

        task_info = result.get("task_info")
        if result.get("error") == "run_not_found":
            return f"Run with ID {result['run_id']} not found for task {task_id}", {"error": "run_not_found"}
        if result.get("error") == "no_runs":
            return f"Task '{task_info['title']}' has no runs yet", {"error": "no_runs"}

        run = result["run"]
        status_info: dict[str, Any] = {
            "task_id": task_info["id"],
            "slug": task_info["slug"],
            "title": task_info["title"],
            "repository": task_info["repository"],
            "run": run,
        }

        message = f"Task '{task_info['title']}' ({task_info['slug']})\nStatus: {run['status_display']}\n"
        if run["stage"]:
            message += f"Current stage: {run['stage']}\n"
        if run["branch"]:
            message += f"Branch: {run['branch']}\n"
        if run["error_message"]:
            message += f"Error: {run['error_message']}\n"
        if run["output"]:
            message += f"Output: {run['output']}\n"

        return message, status_info


class GetTaskRunLogsTool(MaxTool):
    name: str = "get_task_run_logs"
    description: str = """
Get the execution logs from a task run.

Use this tool when the user wants to:
- See what happened during a task execution
- Debug why a task failed
- Review the steps the AI agent took
    """.strip()
    args_schema: type[BaseModel] = GetTaskRunLogsArgs

    async def _arun_impl(self, task_id: str, run_id: str | None = None) -> tuple[str, dict[str, Any]]:
        may_read = analytics_context_reader(team_id=self._team.id, user_id=self._user.id)

        @sync_to_async
        def get_task_and_run():
            task = (
                Task.objects.filter(id=task_id, team=self._team, deleted=False)
                .filter(task_visibility_q(self._user.id))
                .first()
            )

            if not task:
                return {"error": "not_found"}

            if run_id:
                task_run = TaskRun.objects.filter(id=run_id, task=task).first()
            else:
                task_run = task.latest_run

            if not task_run:
                return {
                    "error": "no_runs" if not run_id else "run_not_found",
                    "task_title": task.title,
                    "run_id": run_id,
                }

            if "analytics_query_context" in (task_run.state or {}):
                if not may_read(task_run.state["analytics_query_context"]):
                    return {"error": "permission_denied"}
                return {
                    "task_id": str(task.id),
                    "run_id": str(task_run.id),
                    "logs_api_url": f"/api/projects/{self._team.id}/tasks/{task.id}/runs/{task_run.id}/logs/",
                }

            return {
                "task_id": str(task.id),
                "task_title": task.title,
                "run_id": str(task_run.id),
                "status": task_run.status,
                "status_display": task_run.get_status_display(),
                "log_url": task_run.log_url,
            }

        result = await get_task_and_run()

        if result.get("error") == "permission_denied":
            return "You do not have access to the analytics data in this run.", result
        if result.get("logs_api_url"):
            return f"Read this run's logs through the authenticated endpoint: {result['logs_api_url']}", result

        if result.get("error") == "not_found":
            return f"Task with ID {task_id} not found", {"error": "not_found"}

        if result.get("error") == "run_not_found":
            return f"Run with ID {result['run_id']} not found for task {task_id}", {"error": "run_not_found"}
        if result.get("error") == "no_runs":
            return f"Task '{result['task_title']}' has no runs yet", {"error": "no_runs"}

        presigned_url = object_storage.get_presigned_url(result["log_url"], expiration=3600)

        if not presigned_url:
            return "Unable to generate log download URL", {"error": "presign_failed"}

        return (
            f"Logs for task '{result['task_title']}' run {result['run_id']} (status: {result['status_display']}).\n"
            f"Download logs from: {presigned_url}\n"
            f"(URL expires in 1 hour)",
            {
                "task_id": result["task_id"],
                "run_id": result["run_id"],
                "status": result["status"],
                "log_url": presigned_url,
                "expires_in": 3600,
            },
        )


class ListTasksTool(MaxTool):
    name: str = "list_tasks"
    description: str = """
List tasks in the current project with optional filtering.

Use this tool when the user wants to:
- See all tasks in the project
- Find tasks for a specific repository
- Filter tasks by their origin (error_tracking, user_created, etc.)
    """.strip()
    args_schema: type[BaseModel] = ListTasksArgs

    async def _arun_impl(
        self, origin_product: str | None = None, repository: str | None = None, limit: int = 10
    ) -> tuple[str, dict[str, Any]]:
        @sync_to_async
        def query_tasks():
            qs = (
                Task.objects.filter(team=self._team, deleted=False, internal=False)
                .filter(task_visibility_q(self._user.id, self._team.id))
                .order_by("-created_at")
            )

            if origin_product:
                qs = qs.filter(origin_product=origin_product)

            if repository:
                repo_str = repository.strip().lower()
                if "/" in repo_str:
                    qs = qs.filter(repository__iexact=repo_str)
                else:
                    qs = qs.filter(repository__iendswith=f"/{repo_str}")

            tasks = list(qs.prefetch_related("runs")[:limit])

            task_list = []
            lines = [f"Found {len(tasks)} task(s):\n"] if tasks else []

            for task in tasks:
                latest_run = task.latest_run
                status = latest_run.get_status_display() if latest_run else "Not run"

                lines.append(f"- {task.slug} (ID: {task.id}): {task.title}")
                lines.append(f"  Status: {status} | Repository: {task.repository or 'N/A'}")

                task_list.append(
                    {
                        "id": str(task.id),
                        "slug": task.slug,
                        "title": task.title,
                        "repository": task.repository,
                        "origin_product": task.origin_product,
                        "status": latest_run.status if latest_run else None,
                    }
                )

            return {"tasks": task_list, "lines": lines}

        result = await query_tasks()

        if not result["tasks"]:
            return "No tasks found matching the criteria", {"tasks": []}

        return "\n".join(result["lines"]), {"tasks": result["tasks"]}


class ListTaskRunsTool(MaxTool):
    name: str = "list_task_runs"
    description: str = """
List all runs for a specific task.

Use this tool when the user wants to:
- See the history of runs for a task
- Find a specific run by looking at the list
- Compare different runs of the same task
    """.strip()
    args_schema: type[BaseModel] = ListTaskRunsArgs

    async def _arun_impl(self, task_id: str, limit: int = 10) -> tuple[str, dict[str, Any]]:
        may_read = analytics_context_reader(team_id=self._team.id, user_id=self._user.id)

        @sync_to_async
        def get_task_and_runs():
            task = (
                Task.objects.filter(id=task_id, team=self._team, deleted=False)
                .filter(task_visibility_q(self._user.id))
                .first()
            )

            if not task:
                return {"error": "not_found"}

            runs = list(TaskRun.objects.filter(task=task).order_by("-created_at")[:limit])

            task_info = {
                "id": str(task.id),
                "slug": task.slug,
                "title": task.title,
            }

            run_list = []
            lines = [f"Task '{task.title}' ({task.slug}) - {len(runs)} run(s):\n"] if runs else []

            for run in runs:
                if "analytics_query_context" in (run.state or {}) and not may_read(
                    run.state["analytics_query_context"]
                ):
                    return {"error": "permission_denied"}
                lines.append(f"- Run ID: {run.id}")
                lines.append(f"  Status: {run.get_status_display()} | Stage: {run.stage or 'N/A'}")
                lines.append(f"  Created: {run.created_at.isoformat()}")
                if run.error_message:
                    truncated = run.error_message[:100]
                    suffix = "..." if len(run.error_message) > 100 else ""
                    lines.append(f"  Error: {truncated}{suffix}")

                run_list.append(
                    {
                        "run_id": str(run.id),
                        "status": run.status,
                        "stage": run.stage,
                        "branch": run.branch,
                        "created_at": run.created_at.isoformat(),
                        "completed_at": run.completed_at.isoformat() if run.completed_at else None,
                        "error_message": run.error_message,
                    }
                )

            return {"task_info": task_info, "runs": run_list, "lines": lines}

        result = await get_task_and_runs()

        if result.get("error") == "permission_denied":
            return "You do not have access to the analytics data in these runs.", result

        if result.get("error") == "not_found":
            return f"Task with ID {task_id} not found", {"error": "not_found"}

        task_info = result["task_info"]
        run_list = result["runs"]
        lines = result["lines"]

        if not run_list:
            return (
                f"Task '{task_info['title']}' ({task_info['slug']}) has no runs yet",
                {"task_id": task_info["id"], "runs": []},
            )

        return "\n".join(lines), {"task_id": task_info["id"], "slug": task_info["slug"], "runs": run_list}


class ListRepositoriesTool(MaxTool):
    name: str = "list_repositories"
    description: str = """
List available GitHub repositories that can be used for tasks.

Use this tool when the user wants to:
- See which repositories are available for creating tasks
- Find a specific repository by name
- Check if a repository is connected via GitHub integration
    """.strip()
    args_schema: type[BaseModel] = ListRepositoriesArgs

    async def _arun_impl(self, search: str | None = None) -> tuple[str, dict[str, Any]]:
        from posthog.models.integration import GitHubIntegration

        @sync_to_async
        def get_repositories():
            integrations = IntegrationManager.github.oauth.list(self._team.id)

            all_repos: list[dict[str, str]] = []

            for integration in integrations:
                try:
                    github = GitHubIntegration(integration, source="tasks", priority=Priority.NORMAL)
                    org = github.organization()
                    repos = github.list_all_cached_repositories()

                    for repo in repos:
                        repo_name = repo["name"]
                        full_name = repo["full_name"]
                        if search:
                            if search.lower() not in repo_name.lower():
                                continue
                        all_repos.append(
                            {
                                "repository": full_name,
                                "organization": org,
                                "name": repo_name,
                            }
                        )
                except Exception:
                    continue

            return all_repos

        repos = await get_repositories()

        if not repos:
            if search:
                return f"No repositories found matching '{search}'", {"repositories": []}
            settings_url = "/integrations/github"
            return (
                f"No GitHub repositories available. Please connect a GitHub integration in Settings: {settings_url}",
                {"repositories": [], "settings_url": settings_url},
            )

        lines = [f"Found {len(repos)} repository(ies):\n"]
        for repo in repos:
            lines.append(f"- {repo['repository']}")

        return "\n".join(lines), {"repositories": repos}