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.

28.5 KB
Raw Blame
import uuid
import asyncio
import logging
from datetime import timedelta
from typing import TYPE_CHECKING, Any, Literal, Optional

from django.conf import settings
from django.db import transaction
from django.utils import timezone as django_timezone

import posthoganalytics
from asgiref.sync import sync_to_async
from opentelemetry import trace
from temporalio.common import RetryPolicy, WorkflowIDReusePolicy
from temporalio.exceptions import WorkflowAlreadyStartedError

from posthog.models.team.team import Team
from posthog.temporal.common.client import async_connect, sync_connect
from posthog.temporal.common.scoped import scoped_temporal
from posthog.temporal.oauth import PosthogMcpScopes

from products.tasks.backend.constants import AGENT_OTEL_TELEMETRY_STATE_KEY, OVERLAP_CLONE_BOOT_FEATURE_FLAG
from products.tasks.backend.error_telemetry import truncate_error_message
from products.tasks.backend.feature_flags import agent_otel_telemetry_enabled_for_state
from products.tasks.backend.logic.services.dev_stack_image import DEV_STACK_IMAGE_NAME
from products.tasks.backend.logic.services.dev_stack_image_refresh import reconcile_dev_stack_image
from products.tasks.backend.logic.services.dev_stack_image_state import DevStackImageState
from products.tasks.backend.logic.services.run_actor import get_actor_distinct_id, get_task_run_credential_user
from products.tasks.backend.logic.services.workflow_step_resume import resume_workflow_step_for_run
from products.tasks.backend.logic.stream.redis_stream import (
    TASK_RUN_STREAM_INITIAL_GENERATION,
    get_task_run_stream_generation,
)
from products.tasks.backend.metrics import observe_task_run_terminal, observe_task_run_workflow_start
from products.tasks.backend.models import TaskRun
from products.tasks.backend.redis import run_uses_dedicated_stream
from products.tasks.backend.temporal.bake_dev_stack_image.workflow import BakeDevStackImageInput
from products.tasks.backend.temporal.build_image.workflow import BuildSandboxImageInput
from products.tasks.backend.temporal.constants import (
    SEND_STEER_SIGNAL,
    STEERING_PROTOCOL_QUERY,
    STEERING_PROTOCOL_QUERY_TIMEOUT,
    STEERING_PROTOCOL_VERSION,
)
from products.tasks.backend.temporal.metrics import StepTimer
from products.tasks.backend.temporal.oauth import dispatched_run_scopes
from products.tasks.backend.temporal.process_task.workflow import PendingFollowup, ProcessTaskInput
from products.tasks.backend.temporal.run_trace import run_trace_context
from products.tasks.backend.temporal.slack_relay.activities import RelaySlackMessageInput

if TYPE_CHECKING:
    from temporalio.client import Client

logger = logging.getLogger(__name__)

_PRE_START_STATUSES: tuple[str, ...] = (TaskRun.Status.NOT_STARTED, TaskRun.Status.QUEUED)

_BOOT_ROLLOUT_FLAGS: tuple[tuple[str, str], ...] = (("overlap_clone_boot_enabled", OVERLAP_CLONE_BOOT_FEATURE_FLAG),)


def tag_startup_dispatch(task_run: TaskRun | None) -> None:
    if task_run is not None and not task_run.task.is_scout_experiment:
        posthoganalytics.tag("run_id", str(task_run.id))
        posthoganalytics.tag("origin_product", task_run.task.origin_product)
        posthoganalytics.tag("run_environment", task_run.environment)
        trace.get_current_span().set_attributes(
            {
                "run_id": str(task_run.id),
                "origin_product": task_run.task.origin_product or "unknown",
            }
        )


def _normalize_slack_context(slack_thread_context: Optional[Any]) -> Optional[dict[str, Any]]:
    """Convert slack_thread_context to dict if needed."""
    if slack_thread_context is None:
        return None
    if hasattr(slack_thread_context, "to_dict"):
        return slack_thread_context.to_dict()
    return slack_thread_context


def _record_prefixed_workflow_id(run_id: str, workflow_id: str) -> None:
    """Persist a non-default workflow ID on the run before starting it.

    A prefixed ID isn't derivable from (task_id, run_id), so row→workflow lookups (the heartbeat
    relay, follow-up signals, Temporal UI links) read it back from `state` via `TaskRun.workflow_id`.
    """
    TaskRun.update_state_atomic(run_id, updates={"workflow_id": workflow_id})


def _terminalize_unstarted_task_run(run_id: str, error_message: str) -> bool:
    try:
        with transaction.atomic():
            task_run = TaskRun.objects.select_for_update().get(id=run_id)
            if task_run.status not in _PRE_START_STATUSES:
                logger.info(
                    "task_processing_start_failure_not_terminalized",
                    extra={
                        "run_id": run_id,
                        "status": task_run.status,
                    },
                )
                return False

            task_run.status = TaskRun.Status.FAILED
            task_run.error_message = error_message
            task_run.completed_at = django_timezone.now()
            task_run.save(update_fields=["status", "error_message", "completed_at"])
    except TaskRun.DoesNotExist:
        logger.warning("task_processing_start_failure_task_run_missing", extra={"run_id": run_id})
        return False

    observe_task_run_terminal(task_run, error_type="workflow_start_failed", termination_reason=None)
    task_run.publish_stream_state_event()
    task_run.capture_event(
        "task_run_failed",
        {
            "error_message": truncate_error_message(error_message),
            "error_type": "workflow_start_failed",
            "duration_seconds": task_run._duration_seconds(),
        },
    )

    resume_workflow_step_for_run(task_run)
    return True


async def _terminalize_unstarted_task_run_async(run_id: str, error_message: str) -> bool:
    return await sync_to_async(_terminalize_unstarted_task_run)(run_id, error_message)


def _get_task_run_for_metrics(run_id: str) -> TaskRun | None:
    try:
        return TaskRun.objects.select_related("task").get(id=run_id)
    except Exception:
        return None


def _evaluate_boot_rollout_flag(
    flag_key: str,
    *,
    distinct_id: str,
    organization_id: str,
    run_id: str,
    task_id: str,
) -> bool:
    try:
        return bool(
            posthoganalytics.feature_enabled(
                flag_key,
                distinct_id=distinct_id,
                groups={"organization": organization_id},
                group_properties={"organization": {"id": organization_id}},
                only_evaluate_locally=False,
                send_feature_flag_events=False,
            )
        )
    except Exception as e:
        logger.warning(
            "boot_rollout_capture_flag_failed",
            extra={"run_id": run_id, "task_id": task_id, "flag_key": flag_key, "error": str(e)},
        )
        return False


@StepTimer("capture_dispatch_flags")
def _capture_run_feature_flags(run_id: str) -> dict[str, Any]:
    """Evaluate per-run rollout flags once at dispatch and stamp them into run state.

    Idempotent per key, so retries and resumes keep the decision the run started with.
    Returns the run state after stamping, or an empty state when the run is missing.
    """
    try:
        task_run = TaskRun.objects.select_related("task__created_by", "task__team").get(id=run_id)
    except Exception:
        logger.exception("run_feature_flag_capture_run_missing", extra={"run_id": run_id})
        return {}

    state = task_run.state or {}
    generation = get_task_run_stream_generation(run_id, run_uses_dedicated_stream(state))
    if state.get("stream_generation") != generation:
        TaskRun.update_state_atomic(run_id, updates={"stream_generation": generation})
        state = {**state, "stream_generation": generation}

    need_otel_telemetry = not isinstance(state.get(AGENT_OTEL_TELEMETRY_STATE_KEY), bool)
    pending_boot_flags = [
        (state_key, flag_key)
        for state_key, flag_key in _BOOT_ROLLOUT_FLAGS
        if not isinstance(state.get(state_key), bool)
    ]
    if not need_otel_telemetry and not pending_boot_flags:
        return state

    task = task_run.task
    organization_id = str(task.team.organization_id)
    distinct_id = (
        task.created_by.distinct_id if task.created_by and task.created_by.distinct_id else "process_task_workflow"
    )
    actor_user = get_task_run_credential_user(task, state)
    boot_distinct_id = get_actor_distinct_id(actor_user) if actor_user else distinct_id

    boot_flag_values: dict[str, bool] = {
        state_key: _evaluate_boot_rollout_flag(
            flag_key,
            distinct_id=boot_distinct_id,
            organization_id=organization_id,
            run_id=run_id,
            task_id=str(task.id),
        )
        for state_key, flag_key in pending_boot_flags
    }

    def _stamp_flags(latest_state: dict[str, Any]) -> None:
        if need_otel_telemetry and not isinstance(latest_state.get(AGENT_OTEL_TELEMETRY_STATE_KEY), bool):
            latest_state[AGENT_OTEL_TELEMETRY_STATE_KEY] = True
        for state_key, value in boot_flag_values.items():
            if not isinstance(latest_state.get(state_key), bool):
                latest_state[state_key] = value

    captured_state = TaskRun.mutate_state_atomic(task_run.id, _stamp_flags)
    logger.info(
        "run_feature_flags_captured",
        extra={
            "run_id": run_id,
            "task_id": str(task.id),
            "agent_otel_telemetry_enabled": captured_state.get(AGENT_OTEL_TELEMETRY_STATE_KEY),
            **{state_key: captured_state.get(state_key) for state_key, _ in _BOOT_ROLLOUT_FLAGS},
        },
    )
    return captured_state


async def start_process_task_workflow(
    client: "Client",
    workflow_input: ProcessTaskInput,
    *,
    workflow_id: str,
    id_reuse_policy: WorkflowIDReusePolicy,
    run_state: dict[str, Any],
    rpc_timeout: timedelta | None = None,
) -> None:
    if workflow_input.stream_generation is None:
        generation = run_state.get("stream_generation")
        workflow_input.stream_generation = (
            generation if isinstance(generation, str) else TASK_RUN_STREAM_INITIAL_GENERATION
        )
    with run_trace_context(workflow_input.run_id, enabled=agent_otel_telemetry_enabled_for_state(run_state)):
        await client.start_workflow(
            "process-task",
            workflow_input,
            id=workflow_id,
            id_reuse_policy=id_reuse_policy,
            task_queue=settings.TASKS_TASK_QUEUE,
            retry_policy=RetryPolicy(maximum_attempts=3),
            rpc_timeout=rpc_timeout,
        )


async def _aget_task_run_for_metrics(run_id: str) -> TaskRun | None:
    try:
        return await TaskRun.objects.select_related("task").aget(id=run_id)
    except Exception:
        return None


@scoped_temporal(fresh=True, capture_exceptions=False)
@StepTimer("dispatch", status_tag="dispatch_status")
async def execute_task_processing_workflow_async(
    task_id: str,
    run_id: str,
    team_id: int,
    user_id: Optional[int] = None,
    create_pr: bool = True,
    slack_thread_context: Optional[Any] = None,
    skip_user_check: bool = False,
    posthog_mcp_scopes: PosthogMcpScopes = "read_only",
    prewarmed: bool = False,
    workflow_id_prefix: Optional[str] = None,
    initial_message: PendingFollowup | None = None,
) -> None:
    """
    Start the task processing workflow asynchronously. Fire-and-forget.
    Use this from async contexts (e.g., within Temporal activities).
    """
    logger.info(
        "execute_task_processing_workflow_async_called",
        extra={"task_id": task_id, "run_id": run_id},
    )
    # Keep the metrics lookups inside the try: if either raises, the except clauses must still
    # terminalize the run. When they ran before the try, an exception here aborted the dispatch
    # without marking the run FAILED, orphaning it in QUEUED until the 24h janitor swept it.
    # observe_task_run_workflow_start tolerates a None task_run.
    task_run_for_metrics: TaskRun | None = None
    try:
        task_run_for_metrics = await _aget_task_run_for_metrics(run_id)
        tag_startup_dispatch(task_run_for_metrics)
        observe_task_run_workflow_start(task_run_for_metrics, outcome="attempted", reason="requested")
        await Team.objects.select_related("organization").aget(id=team_id)
        run_state = await sync_to_async(_capture_run_feature_flags)(run_id)

        workflow_id = TaskRun.get_workflow_id(task_id, run_id, workflow_id_prefix)
        if workflow_id_prefix:
            await sync_to_async(_record_prefixed_workflow_id)(run_id, workflow_id)
        slack_context_dict = _normalize_slack_context(slack_thread_context)

        workflow_input = ProcessTaskInput(
            run_id=run_id,
            create_pr=create_pr,
            slack_thread_context=slack_context_dict,
            posthog_mcp_scopes=posthog_mcp_scopes,
            prewarmed=prewarmed,
            initial_message=initial_message,
        )

        logger.info(
            "task_processing_starting_workflow",
            extra={"workflow_id": workflow_id, "task_id": task_id, "run_id": run_id},
        )

        with StepTimer("temporal_connect"):
            client = await async_connect()
        await start_process_task_workflow(
            client,
            workflow_input,
            workflow_id=workflow_id,
            id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY,
            run_state=run_state,
        )

        logger.info("task_processing_workflow_started", extra={"task_id": task_id, "run_id": run_id})
        posthoganalytics.tag("dispatch_status", "COMPLETED")
        observe_task_run_workflow_start(task_run_for_metrics, outcome="started", reason="accepted")

    except Team.DoesNotExist as e:
        observe_task_run_workflow_start(task_run_for_metrics, outcome="failed", reason="permission_validation")
        logger.exception(
            "task_processing_permission_validation_failed",
            extra={"task_id": task_id, "run_id": run_id, "error": str(e)},
        )
        await _terminalize_unstarted_task_run_async(
            run_id,
            f"Failed to start task workflow: permission validation failed: {e}",
        )
    except WorkflowAlreadyStartedError:
        posthoganalytics.tag("dispatch_status", "BLOCKED")
        observe_task_run_workflow_start(task_run_for_metrics, outcome="blocked", reason="already_running")
        logger.info(
            "task_processing_workflow_already_running",
            extra={"task_id": task_id, "run_id": run_id},
        )
    except Exception as e:
        observe_task_run_workflow_start(task_run_for_metrics, outcome="failed", reason="temporal_start")
        logger.exception(
            "task_processing_workflow_start_failed",
            extra={"task_id": task_id, "run_id": run_id, "error": str(e)},
        )
        await _terminalize_unstarted_task_run_async(
            run_id,
            f"Failed to start task workflow: {e}",
        )


@posthoganalytics.scoped(fresh=True, capture_exceptions=False)
@StepTimer("dispatch", status_tag="dispatch_status")
def execute_task_processing_workflow(
    task_id: str,
    run_id: str,
    team_id: int,
    user_id: Optional[int] = None,
    create_pr: bool = True,
    slack_thread_context: Optional[Any] = None,
    skip_user_check: bool = False,
    posthog_mcp_scopes: PosthogMcpScopes = "read_only",
    prewarmed: bool = False,
    workflow_id_prefix: Optional[str] = None,
    initial_message: PendingFollowup | None = None,
) -> None:
    """
    Start the task processing workflow synchronously. Fire-and-forget.
    Use this from sync contexts (e.g., API endpoints).
    """
    # Metrics lookups stay inside the try so a failure here can't bypass terminalization and
    # leave the run orphaned in QUEUED (see the async variant above).
    task_run_for_metrics: TaskRun | None = None
    try:
        task_run_for_metrics = _get_task_run_for_metrics(run_id)
        tag_startup_dispatch(task_run_for_metrics)
        observe_task_run_workflow_start(task_run_for_metrics, outcome="attempted", reason="requested")
        logger.info(
            "execute_task_processing_workflow_called",
            extra={"task_id": task_id, "run_id": run_id, "team_id": team_id, "user_id": user_id},
        )

        Team.objects.get(id=team_id)
        run_state = _capture_run_feature_flags(run_id)

        workflow_id = TaskRun.get_workflow_id(task_id, run_id, workflow_id_prefix)
        if workflow_id_prefix:
            _record_prefixed_workflow_id(run_id, workflow_id)
        slack_context_dict = _normalize_slack_context(slack_thread_context)

        workflow_input = ProcessTaskInput(
            run_id=run_id,
            create_pr=create_pr,
            slack_thread_context=slack_context_dict,
            posthog_mcp_scopes=posthog_mcp_scopes,
            prewarmed=prewarmed,
            initial_message=initial_message,
        )

        logger.info(
            "task_processing_connecting_temporal",
            extra={"task_id": task_id, "task_queue": settings.TASKS_TASK_QUEUE},
        )

        with StepTimer("temporal_connect"):
            client = sync_connect()

        logger.info(
            "task_processing_temporal_connected",
            extra={"workflow_id": workflow_id, "task_id": task_id, "run_id": run_id},
        )

        asyncio.run(
            start_process_task_workflow(
                client,
                workflow_input,
                workflow_id=workflow_id,
                id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY,
                run_state=run_state,
            )
        )

        logger.info("task_processing_workflow_started", extra={"task_id": task_id, "run_id": run_id})
        posthoganalytics.tag("dispatch_status", "COMPLETED")
        observe_task_run_workflow_start(task_run_for_metrics, outcome="started", reason="accepted")

    except Team.DoesNotExist as e:
        observe_task_run_workflow_start(task_run_for_metrics, outcome="failed", reason="permission_validation")
        logger.exception(
            "task_processing_permission_validation_failed",
            extra={"task_id": task_id, "run_id": run_id, "error": str(e)},
        )
        _terminalize_unstarted_task_run(
            run_id,
            f"Failed to start task workflow: permission validation failed: {e}",
        )
    except WorkflowAlreadyStartedError:
        posthoganalytics.tag("dispatch_status", "BLOCKED")
        observe_task_run_workflow_start(task_run_for_metrics, outcome="blocked", reason="already_running")
        logger.info(
            "task_processing_workflow_already_running",
            extra={"task_id": task_id, "run_id": run_id},
        )
    except Exception as e:
        observe_task_run_workflow_start(task_run_for_metrics, outcome="failed", reason="temporal_start")
        logger.exception(
            "task_processing_workflow_start_failed",
            extra={"task_id": task_id, "run_id": run_id, "error": str(e)},
        )
        _terminalize_unstarted_task_run(
            run_id,
            f"Failed to start task workflow: {e}",
        )


def redispatch_orphaned_task_run(run_id: str) -> str:
    """Re-dispatch a run stuck in QUEUED whose create-time on_commit dispatch never fired.

    Idempotent and recover-only: ``ALLOW_DUPLICATE_FAILED_ONLY`` starts a workflow only when
    none is live for this run, so a run that is already running (row not yet flipped to
    IN_PROGRESS) is left untouched. Never terminalizes the run — a transient Temporal failure
    just retries on the next sweep, and the 24h killer remains the only path that fails a run.

    Returns an outcome for metrics/logs: ``recovered`` (workflow started), ``already_running``
    (a workflow already exists), ``left_queue`` (row is no longer QUEUED), ``skipped_prewarmed``
    (owned by the prewarmed reaper), ``skipped_local`` (desktop-driven run, nothing to recover),
    ``error`` (transient).
    """
    from temporalio.exceptions import WorkflowAlreadyStartedError  # noqa: PLC0415 — keep temporalio off the import path

    task_run = (
        TaskRun.objects.select_related("task")  # nosemgrep: celery-task-team-scope-audit
        .filter(id=run_id, status=TaskRun.Status.QUEUED)
        .first()
    )
    if task_run is None:
        return "left_queue"

    # Local (desktop) runs idle in QUEUED while the user's local agent drives them — there is no
    # lost dispatch to recover. Starting a cloud workflow here would hijack the live session: the
    # sandbox boots without the repo ever being cloned, burns its retries, and marks the user's
    # run FAILED. The sweep already filters these out (environment=CLOUD); this guards direct callers.
    if task_run.environment == TaskRun.Environment.LOCAL:
        return "skipped_local"

    # Prewarmed runs idle in QUEUED awaiting the user's first message; the dedicated prewarmed
    # reaper *kills* them if never activated. Recovering one would boot an agent with no prompt
    # (and re-dispatching without the prewarmed flag would change its boot behaviour), so skip.
    if isinstance(task_run.state, dict) and task_run.state.get("prewarmed"):
        return "skipped_prewarmed"

    task = task_run.task
    task_id = str(task.id)
    # create_and_run persists these on the row; the bootstrap/start path does not, so fall back to
    # deriving mcp scopes from run_source exactly as _trigger_task_processing_workflow does.
    pending = task_run.state.get("pending_dispatch") if isinstance(task_run.state, dict) else None
    dispatch_params = pending if isinstance(pending, dict) else {}
    workflow_id_prefix = dispatch_params.get("workflow_id_prefix")
    workflow_id = TaskRun.get_workflow_id(task_id, run_id, workflow_id_prefix)
    if workflow_id_prefix:
        _record_prefixed_workflow_id(run_id, workflow_id)
    workflow_input = ProcessTaskInput(
        run_id=run_id,
        create_pr=dispatch_params.get("create_pr", True),
        slack_thread_context=dispatch_params.get("slack_thread_context"),
        posthog_mcp_scopes=dispatched_run_scopes(task, task_run.state),
    )

    observe_task_run_workflow_start(task_run, outcome="attempted", reason="reconcile")
    run_state = _capture_run_feature_flags(run_id)
    try:
        client = sync_connect()
        asyncio.run(
            start_process_task_workflow(
                client,
                workflow_input,
                workflow_id=workflow_id,
                id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY,
                run_state=run_state,
            )
        )
    except WorkflowAlreadyStartedError:
        observe_task_run_workflow_start(task_run, outcome="blocked", reason="reconcile_already_running")
        return "already_running"
    except Exception as e:
        observe_task_run_workflow_start(task_run, outcome="failed", reason="reconcile_error")
        logger.warning(
            "task_run_reconcile_dispatch_failed",
            extra={"run_id": run_id, "task_id": task_id, "error": str(e)},
        )
        return "error"

    observe_task_run_workflow_start(task_run, outcome="started", reason="reconcile")
    logger.info("task_run_reconcile_dispatch_started", extra={"run_id": run_id, "task_id": task_id})
    return "recovered"


def resume_task_in_cloud_workflow(run_id: str, workflow_id: str) -> None:
    run_state = _capture_run_feature_flags(run_id)
    client = sync_connect()
    asyncio.run(
        start_process_task_workflow(
            client,
            ProcessTaskInput(run_id=run_id),
            workflow_id=workflow_id,
            # TERMINATE_IF_RUNNING closes any prior workflow under this ID
            # atomically before starting the new one, avoiding the async-cancel
            # race where a best-effort cancel signal hasn't landed yet.
            id_reuse_policy=WorkflowIDReusePolicy.TERMINATE_IF_RUNNING,
            run_state=run_state,
        )
    )


def execute_bake_dev_stack_image_workflow(
    publish_name: str = DEV_STACK_IMAGE_NAME, *, trigger: Literal["nightly", "base_changed", "manual"] = "manual"
) -> None:
    """Start (or restart) the bake of the prebaked PostHog dev-stack VM image.

    TERMINATE_IF_RUNNING: a bake stuck from the previous night gets replaced by the
    fresh one instead of blocking it.
    """
    target = DevStackImageState.target(publish_name)
    if target is not None:
        reconcile_dev_stack_image(target, trigger=trigger)
        return
    client = sync_connect()
    asyncio.run(
        client.start_workflow(
            "bake-dev-stack-image",
            BakeDevStackImageInput(publish_name=publish_name, trigger=trigger),
            id=f"bake-dev-stack-image-{publish_name}",
            id_reuse_policy=WorkflowIDReusePolicy.TERMINATE_IF_RUNNING,
            task_queue=settings.TASKS_TASK_QUEUE,
            # A single workflow attempt: each bake is a full 15-25 minute stack build, the
            # activity inside already retries once, and the nightly schedule plus the
            # base-digest sweep are the outer retry loop. Workflow-level retries would
            # multiply with the activity's into up to four consecutive bakes.
            retry_policy=RetryPolicy(maximum_attempts=1),
        )
    )


def execute_build_sandbox_image_workflow(image_id: str, team_id: int, *, refresh: bool = False) -> None:
    """Start (or restart) the scan → build → publish workflow for a custom sandbox image."""
    client = sync_connect()
    asyncio.run(
        client.start_workflow(
            "build-sandbox-image",
            BuildSandboxImageInput(image_id=image_id, team_id=team_id, refresh=refresh),
            id=f"build-sandbox-image-{image_id}",
            id_reuse_policy=WorkflowIDReusePolicy.TERMINATE_IF_RUNNING,
            task_queue=settings.TASKS_TASK_QUEUE,
            retry_policy=RetryPolicy(maximum_attempts=3),
        )
    )


def signal_task_followup_message(
    workflow_id: str,
    message: str | None,
    artifact_ids: list[str],
    message_id: str | None = None,
    actor_user_id: int | None = None,
    context: dict[str, Any] | None = None,
    *,
    steer: bool = False,
    rpc_timeout: timedelta | None = None,
) -> None:
    """Legacy positional signal args stay frozen for worker deploy compatibility."""
    client = sync_connect()
    handle = client.get_workflow_handle(workflow_id)

    async def signal() -> None:
        signal_name = "send_followup_message"
        if steer:
            try:
                protocol_version = await handle.query(
                    STEERING_PROTOCOL_QUERY,
                    rpc_timeout=STEERING_PROTOCOL_QUERY_TIMEOUT,
                )
            except Exception:
                logger.info(
                    "task_followup_steering_capability_unavailable",
                    extra={"workflow_id": workflow_id},
                    exc_info=True,
                )
            else:
                if isinstance(protocol_version, int) and protocol_version >= STEERING_PROTOCOL_VERSION:
                    signal_name = SEND_STEER_SIGNAL
        signal_args = [message, artifact_ids, message_id, actor_user_id, context]
        if rpc_timeout is None:
            await handle.signal(signal_name, args=signal_args)
        else:
            await handle.signal(signal_name, args=signal_args, rpc_timeout=rpc_timeout)

    asyncio.run(signal())


def signal_agent_final_text(workflow_id: str, text: str, trace_id: str | None = None) -> None:
    """Give the live agent-design reply of a running task the turn's whole answer.

    The relay replaces its streamed text deltas with this text, so the answer shows one time
    even when this signal lands between two deltas."""
    client = sync_connect()
    handle = client.get_workflow_handle(workflow_id)
    asyncio.run(handle.signal("agent_final_text", {"text": text, "trace_id": trace_id}))


def execute_posthog_code_agent_relay_workflow(
    run_id: str,
    text: str,
    relay_id: str | None = None,
    user_message_ts: str | None = None,
    delete_progress: bool = True,
    reaction_emoji: str | None = None,
    message_id: str | None = None,
    trace_id: str | None = None,
    offer_reply_suggestions: bool = False,
    offer_feature_tip: bool = False,
) -> str:
    relay_id = relay_id or str(uuid.uuid4())
    workflow_id = f"posthog-code-agent-relay-{run_id}-{relay_id}"

    client = sync_connect()
    asyncio.run(
        client.start_workflow(
            "posthog-code-agent-relay",
            RelaySlackMessageInput(
                run_id=run_id,
                relay_id=relay_id,
                text=text,
                user_message_ts=user_message_ts,
                delete_progress=delete_progress,
                reaction_emoji=reaction_emoji,
                message_id=message_id,
                trace_id=trace_id,
                offer_reply_suggestions=offer_reply_suggestions,
                offer_feature_tip=offer_feature_tip,
            ),
            id=workflow_id,
            id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE,
            task_queue=settings.TASKS_TASK_QUEUE,
        )
    )
    return relay_id