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.

33.1 KB
Raw Blame
"""
Contract types for the tasks product.

Stable, framework-free frozen dataclasses describing the data the tasks product
exposes across product boundaries. No Django, no DRF — just stdlib/pydantic types.

These use ``pydantic.dataclasses.dataclass`` (same shape as the stdlib variant, but
with runtime validation on construction) so a malformed mapper surfaces a
``ValidationError`` at the boundary instead of a confusing failure deep in a caller.

Behavioral/wiring surfaces (sandbox classes, the multi-turn agent machinery, temporal
workflows, max tools, webhook handlers) are NOT data and are not modelled here — they
cross the boundary through sibling facade submodules (``sandbox``, ``warm``,
``agents``, ``temporal``, ``max_tools``, ``webhooks``, …), with DTOs here only for
their data results.
"""

from datetime import date, datetime
from enum import StrEnum
from typing import Literal
from uuid import UUID

from pydantic import Field
from pydantic.dataclasses import dataclass

from posthog.enums import LabeledStrEnum

# Re-exported: the exception is defined in an import-light module so ``storage.py`` can raise it
# without dragging this module onto the ``django.setup()`` path.
from products.tasks.backend.storage_errors import TaskRunLogAppendUnserialized as TaskRunLogAppendUnserialized


# Each label repeats its value, because the API documents these choices as plain values.
class DesktopAccessReason(LabeledStrEnum):
    STARTUP_PLAN = "startup_plan", "startup_plan"
    PREPAID_CREDITS = "prepaid_credits", "prepaid_credits"


@dataclass(frozen=True)
class TaskDTO:
    """A code task."""

    id: UUID
    team_id: int
    title: str
    description: str
    origin_product: str
    repository: str | None
    internal: bool
    archived: bool
    created_at: datetime
    updated_at: datetime
    created_by_id: int | None = None
    task_number: int | None = None
    slug: str = ""


@dataclass(frozen=True, kw_only=True)
class TaskAccessScope:
    """Task IDs a user can or cannot access through channel visibility rules."""

    user_id: int
    has_resource_access: bool
    allowed_ids: frozenset[str]
    blocked_ids: frozenset[str]


@dataclass(frozen=True, kw_only=True)
class AgentTaskRunDTO:
    """Identity and workflow handle for a newly dispatched agent task."""

    task_id: UUID
    run_id: UUID
    team_id: int
    workflow_id: str


@dataclass(frozen=True, kw_only=True)
class AgentStartupFailure:
    provider: Literal["claude", "codex", "pi"]
    phase: Literal["session_setup", "sdk_initialization", "setup_hooks"]
    reason: (
        Literal[
            "credential_unavailable",
            "credential_service_unavailable",
            "org_pin_api_key_conflict",
            "org_verify_failed",
            "org_pin_mismatch",
            "managed_settings_invalid",
            "remote_settings_required_unavailable",
            "gateway_signin_required",
            "gateway_access_denied",
            "proxy_invalid",
            "temp_dir_unusable",
            "cwd_unavailable",
            "shell_tool_missing",
            "session_held_by_background",
            "worktree_resume_refused",
            "worktree_unverified",
            "cli_version_too_old",
            "bypass_root",
            "sandbox_required_unavailable",
            "provider_not_allowed",
            "org_config_required_unavailable",
            "org_config_refused",
        ]
        | None
    )
    retryability: Literal["requires_action", "transient", "unknown"]


@dataclass(frozen=True, kw_only=True)
class SessionFile:
    """A text file a custom-prompt session puts in the sandbox before its first turn.

    The agent server writes it under the run's attachments directory and lists its path in the
    first prompt, so the agent and any sub-agent it starts can read it from disk.
    """

    name: str
    content: str


@dataclass(frozen=True)
class StreamNotificationDelivery:
    """Where a server-originated stream notification landed.

    ``live`` reached the run's Redis stream, so connected threads show the frame now. ``persisted``
    reached the run's S3 log, so a thread loaded after the stream expires replays it too.
    """

    live: bool
    persisted: bool


@dataclass(frozen=True)
class SignalImplementationRunDTO:
    """Identity of a signals-origin ("self-driving") implementation run that produced a PR.

    Returned by ``find_signal_implementation_run``. Consumers (stamphog's inbox carve-out) use it
    to confirm a bot-authored PR is a PostHog Code self-driving implementation and to find whose
    review preferences apply.
    """

    run_id: UUID
    task_id: UUID
    team_id: int
    signal_report_id: UUID
    task_created_by_id: int | None = None


@dataclass(frozen=True)
class WizardCloudRunDTO:
    """A team's active onboarding wizard cloud run.

    Lets the frontend rehydrate the setup-progress FAB from the server when the drop
    flow started the run server-side (so no client-side localStorage handle exists).
    Carries only what the FAB's cloud stream needs to reconnect.
    """

    task_id: UUID
    run_id: UUID
    status: str
    started_at: datetime | None = None


@dataclass(frozen=True)
class TaskRunTokenUsage:
    """Settled token subtotal in micro-USD and whether every request is accounted for."""

    cost_microusd: int | None
    complete: bool


@dataclass(frozen=True, kw_only=True)
class TaskRunSpend:
    created_at: datetime
    run_id: UUID
    task_id: UUID
    cost_microusd: int | None
    complete: bool
    is_terminal: bool
    stage: str
    accounting_failed: bool


@dataclass(frozen=True)
class TaskRunCost:
    """Provider costs in integer USD cents, or None while a source is unavailable or incomplete."""

    token_cost: int | None
    compute_cost: int | None


@dataclass(frozen=True)
class TaskRunDTO:
    """A single execution of a task.

    Carries the derived fields external callers read off a ``TaskRun`` ORM instance
    (``is_terminal``, ``workflow_id``, ``mode``) plus a few denormalised parent-task
    values (``task_origin_product``, ``created_by_distinct_id``, ``pr_url``) so callers
    never need to traverse the ORM relation themselves.
    """

    id: UUID
    task_id: UUID
    team_id: int
    status: str
    environment: str
    stage: str | None
    branch: str | None
    error_message: str | None
    output: dict | None
    state: dict
    artifacts: list = Field(default_factory=list)
    created_at: datetime | None = None
    updated_at: datetime | None = None
    completed_at: datetime | None = None
    is_terminal: bool = False
    workflow_id: str = ""
    mode: str = "background"
    task_origin_product: str | None = None
    task_created_at: datetime | None = None
    created_by_id: int | None = None
    created_by_distinct_id: str | None = None
    pr_url: str | None = None


@dataclass(frozen=True)
class InProgressGithubRunsDTO:
    """In-progress runs that block disconnecting a team GitHub integration."""

    count: int
    oldest_task_id: UUID | None = None
    oldest_task_title: str | None = None


@dataclass(frozen=True)
class WizardPrReadyEmailContextDTO:
    """Everything ``send_wizard_pr_ready_email`` needs to read off a task run's PR-ready state."""

    task_id: UUID
    run_id: UUID
    team_id: int
    origin_product: str
    pr_url: str
    repository: str | None
    branch: str | None
    created_by_id: int | None
    already_sent: bool


@dataclass(frozen=True)
class WarmRunDTO:
    """Outcome of ensuring a warm sandbox run exists for a task."""

    task_id: UUID
    run_id: UUID
    run_status: str
    just_created: bool


@dataclass(frozen=True)
class SlackThreadReferenceDTO:
    """A passive link from a task to a public Slack discussion."""

    url: str
    channel: str
    created_at: str | None = None


@dataclass(frozen=True)
class TaskSlackUnfurlDTO:
    """The task metadata needed to build a Slack unfurl."""

    id: UUID
    title: str
    created_by_id: int | None
    latest_run_status: str | None


@dataclass(frozen=True)
class TaskArtifactSlackUnfurlDTO:
    """The task run artifact metadata needed to build a Slack unfurl."""

    name: str
    content_type: str
    size: int | None
    uploaded_at: datetime | None
    task_id: UUID
    task_title: str
    run_id: UUID
    artifact_id: str
    download_path: str


@dataclass(frozen=True)
class TaskDetailDTO:
    """The HTTP detail representation of a task.

    Mirrors exactly the fields ``TaskSerializer`` emits, in order. ``github_integration`` and
    ``github_user_integration`` are the integration primary keys (or ``None``), matching the
    original ``PrimaryKeyRelatedField`` output. ``signal_report`` is the linked report id (or
    ``None``). ``latest_run`` is the most-recent run as a ``TaskRunDetailDTO`` (or ``None``).
    ``latest_run_id`` carries just that run's id for the conversation envelope, which needs the id
    to reconnect to sandbox logs but not the full (presigned-log) run payload. ``created_by``
    mirrors core ``UserBasicSerializer`` output. ``last_activity_at`` is when something last
    happened in the task, as opposed to ``updated_at``, which is when the row was last written.
    """

    id: UUID
    task_number: int | None
    slug: str
    title: str
    title_manually_set: bool
    description: str
    origin_product: str
    runtime: str
    repository: str | None
    repositories: list[str]
    github_integration: int | None
    github_user_integration: UUID | None
    signal_report: UUID | None
    json_schema: dict | None
    internal: bool
    archived: bool
    archived_at: datetime | None
    ci_prompt: str | None
    latest_run: "TaskRunDetailDTO | None" = None
    created_at: datetime | None = None
    updated_at: datetime | None = None
    last_activity_at: datetime | None = None
    created_by: "TaskUserBasicInfo | None" = None
    latest_run_id: UUID | None = None
    channel: UUID | None = None
    slack_thread_references: list[SlackThreadReferenceDTO] = Field(default_factory=list)
    origin_key: str | None = None
    client_provenance: str | None = None


@dataclass(frozen=True)
class TaskCreateResponseDTO(TaskDetailDTO):
    run_error: str | None = None


@dataclass(frozen=True)
class TaskRunResponseDTO(TaskCreateResponseDTO):
    """The task ``run`` action's response: the refreshed task detail plus the run this call made.

    ``run`` is the run the call created or activated — the payload a caller reads run-scoped ids
    from, instead of inferring them from ``latest_run`` (or, worse, the top-level task ``id``).
    Set on every 200; when ``run_error`` is also set, the run exists but its workflow did not
    start.
    """

    run: "TaskRunDetailDTO | None" = None


@dataclass(frozen=True)
class ChannelDTO:
    """The HTTP representation of a task channel."""

    id: UUID
    name: str
    channel_type: str
    github_integration: int | None
    repositories: list[str]
    auto_archive_after_days: int | None
    created_at: datetime
    created_by: "TaskUserBasicInfo | None" = None
    starred: bool = False
    system_role: str | None = None


@dataclass(frozen=True)
class ChannelContributorsDTO:
    """The people who own at least one task or canvas in a channel, most recently active first."""

    channel: UUID
    people: list["TaskUserBasicInfo"]


@dataclass(frozen=True)
class ProvisionedChannelsDTO:
    channels: list[ChannelDTO]
    personal_created: bool
    general_created: bool


@dataclass(frozen=True)
class ChannelInstructionsDTO:
    """The HTTP representation of a channel's CONTEXT.md instructions version.

    A channel that has never had instructions published reads as a blank
    version 0 — publish against ``base_version: 0`` to create version 1."""

    channel: UUID
    content: str
    version: int
    created_at: datetime | None = None
    created_by: "TaskUserBasicInfo | None" = None


@dataclass(frozen=True)
class TaskThreadMessageDTO:
    """The HTTP representation of one message in a task's thread."""

    id: UUID
    task: UUID
    author_kind: str
    event: str
    payload: dict
    content: str
    created_at: datetime
    author: "TaskUserBasicInfo | None" = None
    forwarded_to_agent_at: datetime | None = None
    forwarded_by: "TaskUserBasicInfo | None" = None


@dataclass(frozen=True)
class ChannelFeedMessageDTO:
    """The HTTP representation of one system announcement in a channel's feed."""

    id: UUID
    channel: UUID
    author_kind: str
    event: str
    payload: dict
    content: str
    created_at: datetime
    author: "TaskUserBasicInfo | None" = None


@dataclass(frozen=True)
class TaskMentionDTO:
    """One @-mention of the requesting user in a task's thread, for the mentions feed."""

    id: UUID
    message_id: UUID
    task_id: UUID
    task_title: str
    channel_id: UUID | None
    channel_name: str | None
    content: str
    created_at: datetime
    author: "TaskUserBasicInfo | None" = None


@dataclass(frozen=True)
class TaskActivityDTO:
    """One entry in the requesting user's task-centric activity feed.

    Lifecycle signals collapse to one row per task, while comment notifications remain
    separate entries. Source fields describe the message or comment tied
    to ``activity_at`` and stay empty for task creation.
    """

    id: UUID
    task_id: UUID | None
    task_title: str
    channel_id: UUID | None
    channel_name: str | None
    activity_at: datetime
    activity_kind: str
    snippet: str
    latest_author: "TaskUserBasicInfo | None" = None
    latest_message_id: UUID | None = None
    latest_comment_id: UUID | None = None
    latest_comment_scope: str | None = None
    latest_comment_item_id: str | None = None
    is_unread: bool = True


@dataclass(frozen=True)
class TaskActivityPageDTO:
    results: list[TaskActivityDTO]
    unread_count: int
    next_before: datetime | None = None
    next_before_id: UUID | None = None


@dataclass(frozen=True)
class TaskArtifactDTO:
    id: str
    type: str
    name: str


@dataclass(frozen=True)
class TaskRunInputFile:
    """An existing server-owned object attached before a task run starts."""

    id: str
    name: str
    storage_path: str
    size_bytes: int
    content_type: str


@dataclass(frozen=True)
class TaskCommentTargetDTO:
    id: str
    type: str
    name: str


@dataclass(frozen=True)
class TaskCommentSummaryDTO:
    id: UUID
    target: TaskCommentTargetDTO
    content: str
    content_truncated: bool
    selected_text: str | None
    created_at: datetime
    reply_count: int
    resolved: bool


@dataclass(frozen=True)
class TaskCommentPageDTO:
    comments: list[TaskCommentSummaryDTO]
    next: str | None


@dataclass(frozen=True)
class TaskCommentEntryDTO:
    id: UUID
    content: str
    content_truncated: bool
    content_next_offset: int | None
    author: str | None
    created_at: datetime
    anchor: dict | None
    canvas_version_id: str | None


@dataclass(frozen=True)
class TaskCommentDetailDTO:
    id: UUID
    target: TaskCommentTargetDTO
    resolved: bool
    comments: list[TaskCommentEntryDTO]
    next: str | None


@dataclass(frozen=True)
class TaskLatestRunSummaryDTO:
    """The latest-run state nested in a task summary response."""

    id: UUID
    status: str | None
    environment: str | None
    mode: Literal["interactive", "background"]
    pr_url: str | None = None
    pr_state: str | None = None
    task_summary: str | None = None


@dataclass(frozen=True)
class TaskSummaryDTO:
    """The HTTP summary representation of a task.

    Mirrors exactly the fields ``TaskSummarySerializer`` emits. ``latest_run`` carries the
    most-recent run's status, environment, mode and pull request (or ``None`` when the task has no runs).
    """

    id: UUID
    title: str
    repository: str | None
    created_by_id: int | None
    created_at: datetime
    updated_at: datetime
    origin_product: str = ""
    latest_run: TaskLatestRunSummaryDTO | None = None


class TaskAnalysisError(Exception):
    """A task analysis could not be created or recorded; ``message`` is safe to surface."""


@dataclass(frozen=True)
class TaskValidationError:
    """A structured validation-error payload the presentation layer renders as a 400/404.

    ``kind`` distinguishes the response shape the original task views built:
      - ``"validation_error"`` -> the ``{type, code, detail, attr}`` body.
      - ``"detail"`` -> a plain ``{"detail": detail}`` body.
      - ``"error"`` -> the ``{"error": detail}`` body.
    ``missing_artifact_ids`` is included on the body only when set.
    """

    kind: str
    detail: str
    code: str | None = None
    attr: str | None = None
    missing_artifact_ids: list[str] | None = None


@dataclass(frozen=True)
class TaskRunResult:
    """Outcome of the task ``run`` action.

    Exactly one of ``task`` / ``error`` is set. ``task`` is the refreshed task detail DTO with
    its new latest run; ``error`` carries the structured error the original view returned inline.
    ``run_id`` names the run this call created or activated, so the view does not have to infer
    it from ``task.latest_run`` (which a concurrent run creation can race past).
    """

    task: "TaskDetailDTO | None" = None
    error: TaskValidationError | None = None
    run_error: str | None = None
    run_id: UUID | None = None


@dataclass(frozen=True)
class StagedArtifactPreparedDTO:
    """One prepared staged upload, mirroring ``TaskStagedArtifactPrepareUploadResponseSerializer``."""

    id: str
    name: str
    type: str
    source: str
    size: int
    content_type: str
    storage_path: str
    expires_in: int
    presigned_post: dict
    metadata: dict | None = None


@dataclass(frozen=True)
class StagedArtifactPrepareResult:
    """Outcome of preparing staged uploads. ``error`` is set when a presigned POST could not be minted."""

    artifacts: list[StagedArtifactPreparedDTO] | None = None
    error: str | None = None


@dataclass(frozen=True)
class StagedArtifactFinalizeResult:
    """Outcome of finalizing staged uploads. ``error`` is set on the first invalid/missing artifact."""

    artifacts: list[dict] | None = None
    error: str | None = None


@dataclass(frozen=True)
class SlackThreadContextRepoResearchDTO:
    """The internal sandbox run the discovery agent used to pick a run's repo."""

    task_id: str
    run_id: str
    status: str | None
    task_processing_workflow_id: str
    task_processing_workflow_url: str | None
    sandbox_url: str | None
    task_view_url: str
    log_url: str | None


@dataclass(frozen=True)
class SlackThreadContextRunDTO:
    """One TaskRun and its associated Temporal workflow handles for the slack-thread debug view."""

    id: str
    status: str
    created_at: datetime | None
    completed_at: datetime | None
    sandbox_url: str | None
    pr_url: str | None
    error_message: str | None
    task_processing_workflow_id: str
    task_processing_workflow_url: str | None
    mention_workflow_id: str | None
    mention_workflow_url: str | None
    task_view_url: str
    log_url: str | None
    admin_url: str
    repo_research: SlackThreadContextRepoResearchDTO | None = None


@dataclass(frozen=True)
class SlackThreadContextThreadDTO:
    """Slack-side identifiers and mapping metadata for a thread → task lookup."""

    url: str
    channel: str
    thread_ts: str
    slack_workspace_id: str | None
    mentioning_slack_user_id: str | None
    queue_workflow_id: str | None
    queue_workflow_url: str | None
    # Null on the no-mapping path, where there is no row to link.
    mapping_admin_url: str | None = None


@dataclass(frozen=True)
class SlackThreadContextTaskDTO:
    """The PostHog Task linked to a Slack thread."""

    id: str
    team_id: int
    title: str
    repository: str | None
    origin_product: str
    created_at: datetime | None
    url: str
    admin_url: str


@dataclass(frozen=True)
class SlackThreadContextDTO:
    """Top-level response for the slack-thread debug endpoint."""

    thread: SlackThreadContextThreadDTO
    task: SlackThreadContextTaskDTO | None = None
    runs: list[SlackThreadContextRunDTO] = Field(default_factory=list)


@dataclass(frozen=True)
class SlackThreadContextResult:
    """Outcome of resolving a slack-thread context.

    ``outcome`` is one of ``"forbidden"`` (403), ``"bad_url"`` (400), ``"no_mapping"`` (404), or
    ``"ok"`` (``context`` set). The error variants carry the partial payload the original view
    returned in the body.
    """

    outcome: str
    context: SlackThreadContextDTO | None = None
    bad_url: str | None = None
    no_mapping_thread: SlackThreadContextThreadDTO | None = None


@dataclass(frozen=True)
class TaskRunDetailDTO:
    """The HTTP detail representation of a task run.

    Mirrors exactly the fields ``TaskRunDetailSerializer`` emits, in order. ``task`` is the
    parent task id (rendered as a string, matching the original ``PrimaryKeyRelatedField``).
    The SMF-derived fields are computed in the facade mapper ``_task_run_detail_to_dto``:
    ``log_url`` is a presigned S3 URL (cached); ``runtime_adapter`` / ``provider`` / ``model`` /
    ``reasoning_effort`` are parsed off the run ``state``. ``artifacts`` carries the run's
    artifact manifest entries verbatim. Reused by the run-detail responses and nested as
    ``latest_run`` by the task detail response.
    """

    id: UUID
    task: UUID
    stage: str | None
    branch: str | None
    status: str
    environment: str
    runtime_adapter: str | None
    provider: str | None
    model: str | None
    reasoning_effort: str | None
    log_url: str | None
    error_message: str | None
    output: dict | None
    task_summary: str | None
    state: dict
    artifacts: list = Field(default_factory=list)
    task_tags: list[str] = Field(default_factory=list)
    created_at: datetime | None = None
    updated_at: datetime | None = None
    completed_at: datetime | None = None
    preview_available: bool = False
    scheduled_at: datetime | None = None


@dataclass(frozen=True)
class TaskRunValidationError:
    """A structured validation-error payload the presentation layer renders as a 400.

    ``kind`` distinguishes the response shape the original view built:
      - ``"validation_error"`` -> the ``{type, code, detail, attr}`` body, fields carried here.
      - ``"detail"`` -> a plain ``{"detail": detail}`` body.
    """

    kind: str
    detail: str
    code: str | None = None
    attr: str | None = None


@dataclass(frozen=True)
class TaskRunCreateResult:
    """Outcome of bootstrapping a task run.

    Exactly one of ``run`` / ``error`` is set. ``error`` carries the structured validation
    error the original view returned inline; the presentation layer maps it to a 400.
    """

    run: "TaskRunDetailDTO | None" = None
    error: TaskRunValidationError | None = None


@dataclass(frozen=True)
class TaskRunLogSliceDTO:
    """Part of a run's conversation log.

    ``content`` is JSONL. ``offset`` is the index in the full log of the first entry after the
    ``preamble`` entries, ``count`` is the number of entries in the full log, and ``turns_before`` is the
    number of user turns that start before ``offset``. ``origin`` is the id of the first run in the chain: the
    chain keeps a limited number of runs, so indexes hold only while the origin stays the same. ``sliced`` is
    false when the run's log cannot be read in parts, so ``content`` is the full log and the other fields carry
    no index.
    """

    content: str
    offset: int
    count: int
    preamble: int = 0
    turns_before: int = 0
    origin: str = ""
    sliced: bool = True


@dataclass(frozen=True)
class TaskRunStreamInfoDTO:
    """The minimal run facts the SSE stream view needs without holding a model.

    ``id`` keys the Redis stream, ``state`` decides dedicated-stream routing,
    ``origin_product`` is the bounded metric label resolved off the parent task, and
    ``is_terminal`` lets the view end immediately when the stream key is already gone.
    ``state_event`` is the run's current ``task_run_state`` frame, emitted before that
    immediate end so a client that never received any state still settles the run.
    """

    id: UUID
    state: dict
    origin_product: str
    is_terminal: bool
    state_event: dict


@dataclass(frozen=True)
class TaskRunSandboxConnectionDTO:
    """A run's live-sandbox connection details, for proxying agent-server commands.

    Carries the sandbox URL and connect token parsed off the run state plus a freshly-minted
    connection token. ``sandbox_url`` is ``None`` when the run has no active sandbox.
    ``run_is_terminal`` disambiguates that case: a terminal run's sandbox is cleaned up and
    never comes back, while a non-terminal run's sandbox may simply not be reachable yet.
    """

    sandbox_url: str | None
    sandbox_connect_token: str | None
    connection_token: str | None = None
    # Query-param name the transport token travels under (provider-specific).
    sandbox_token_param: str = "_modal_connect_token"
    run_is_terminal: bool = False


SPACE_SETUP_SCOPES = (
    "task:write",
    "inbox:write",
    "canvas:write",
    "hog_flow:write",
    # workflows-schedule-create and workflows-test-run require these beside hog_flow:write.
    "person:read",
    "group:read",
    "integration:read",
    # The MCP server reads the caller from `/api/users/@me/` and refuses the whole session without it.
    "user:read",
    "query:read",
    "action:read",
    "data_catalog:read",
    "insight:read",
    "dashboard:read",
    "feature_flag:read",
    "experiment:read",
    "error_tracking:read",
    "session_recording:read",
    "event_definition:read",
    "property_definition:read",
    "project:read",
    "organization:read",
    "survey:read",
)


class SpaceSetupInProgressError(Exception):
    pass


@dataclass(frozen=True)
class SpaceGoalRequest:
    """The metric a goal space is set up to move."""

    statement: str
    period: Literal["day", "week", "month"] = "week"
    direction: Literal["at_least", "at_most"] = "at_least"
    target: str | None = None
    deadline: date | None = None
    insight_short_id: str | None = None


@dataclass(frozen=True)
class SpaceFeatureRequest:
    """The feature a feature space is set up around."""

    name: str
    description: str = ""
    flag_key: str | None = None


@dataclass(frozen=True)
class SpaceSetupRequest:
    """What the space setup task should set the space up for. Exactly one of ``goal`` and
    ``feature`` is set, matching ``kind``."""

    kind: Literal["goal", "feature"]
    goal: SpaceGoalRequest | None = None
    feature: SpaceFeatureRequest | None = None
    repository: str | None = None


@dataclass(frozen=True)
class SpaceSetupStartedDTO:
    """The setup task that now owns the channel's context generation marker."""

    task_id: UUID


@dataclass(frozen=True)
class CreatedTaskDTO:
    """Result of creating-and-running a task.

    ``Task.create_and_run`` returns an ORM instance whose ``latest_run`` is read by
    callers; this contract hands back the ids (and the run, if one was created) without
    leaking the model.
    """

    task_id: UUID
    team_id: int
    latest_run: TaskRunDTO | None = None


@dataclass(frozen=True)
class WorkflowLastRunDTO:
    """The newest task a workflow created, as its last run.

    ``status`` is the task's newest run status, or ``not_started`` when the task has no run yet.
    ``ran_at`` is when that run started, or when the task was made if it has no run.
    """

    hog_flow_id: UUID
    task_id: UUID
    status: str
    ran_at: datetime


@dataclass(frozen=True)
class WorkflowTaskDTO:
    """Outcome of a workflow's "Create AI task" action.

    ``created`` is False when the request replayed an already-used idempotency key and the
    ids belong to the previously created task. ``run_id`` is ``None`` only for a replayed
    task whose run has since been deleted.
    """

    task_id: UUID
    run_id: UUID | None
    created: bool


@dataclass(frozen=True, kw_only=True)
class WorkflowTaskRateLimits:
    """Optional per-project overrides for workflow-created AI task daily limits."""

    per_workflow: int | None = Field(default=None, ge=0)
    per_team: int | None = Field(default=None, ge=0)


@dataclass(frozen=True, kw_only=True)
class WorkflowTaskSlackContext:
    """The Slack thread whose message triggered the workflow run, so the task reports back there.

    ``integration_id`` is the PostHog integration pk stamped on the trigger event;
    ``slack_team_id`` is the Slack workspace id, kept as a fallback for re-resolving the
    integration when the stamped pk is stale. ``slack_user_id`` is empty when a bot
    posted the triggering message. ``message_ts`` is the triggering message itself,
    which differs from ``thread_ts`` when a reply started the run.
    ``is_ext_shared_channel`` comes from the Slack event envelope and decides whether the
    channel needs an approval on file before a task may reply in it.
    """

    integration_id: int
    channel: str
    thread_ts: str
    message_ts: str = ""
    slack_user_id: str = ""
    slack_team_id: str = ""
    is_ext_shared_channel: bool = False


@dataclass(frozen=True)
class DesktopBetaTermsAcceptanceDTO:
    is_desktop_beta_terms_accepted: bool


@dataclass(frozen=True)
class TaskUserBasicInfo:
    """Lightweight user info for display, mirroring core ``UserBasicSerializer`` output.

    Carries exactly the fields that serializer emits so presentation responses stay
    byte-identical when a task/run/environment exposes its ``created_by``.
    """

    id: int
    uuid: UUID
    distinct_id: str
    first_name: str
    last_name: str
    email: str
    is_email_verified: bool | None = None
    hedgehog_config: dict | None = None
    role_at_organization: str | None = None


@dataclass(frozen=True)
class SandboxEnvironmentDTO:
    """A sandbox execution environment."""

    id: UUID
    team_id: int
    name: str
    network_access_level: str
    private: bool
    internal: bool
    include_default_domains: bool
    allowed_domains: list[str] = Field(default_factory=list)
    repositories: list[str] = Field(default_factory=list)
    effective_domains: list[str] = Field(default_factory=list)
    has_environment_variables: bool = False
    environment_variable_keys: list[str] = Field(default_factory=list)
    created_by: TaskUserBasicInfo | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None
    custom_image_id: UUID | None = None
    custom_image_name: str | None = None
    custom_image_status: str | None = None


@dataclass(frozen=True)
class SandboxCustomImageDTO:
    """A user-defined custom base image for cloud task sandboxes (Modal VM runtime)."""

    id: UUID
    team_id: int
    name: str
    description: str
    status: str
    version: int
    modal_image_name: str
    error: str
    repository: str = ""
    private: bool = False
    spec: dict = Field(default_factory=dict)
    spec_yaml: str = ""
    scan_result: dict = Field(default_factory=dict)
    build_log: str = ""
    builder_task_id: UUID | None = None
    created_by: TaskUserBasicInfo | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None


@dataclass(frozen=True)
class SandboxSnapshotDTO:
    """A snapshot of a sandbox image."""

    id: UUID
    external_id: str
    status: str
    repos: list[str] = Field(default_factory=list)


@dataclass(frozen=True)
class SignalReportPrUrlDTO:
    """The PR URL produced by the latest task run for a signal report."""

    report_id: str
    pr_url: str


@dataclass(frozen=True)
class WarmTaskDTO:
    """The draft Task + warm Run birthed by a Code-app warm request."""

    task_id: UUID
    run_id: UUID


@dataclass(frozen=True)
class TaskRunGaugeRow:
    """One metric value keyed by (status, environment, origin_product)."""

    environment: str
    origin_product: str
    value: float
    status: str | None = None


@dataclass(frozen=True)
class TaskRunStateMetricsDTO:
    """Aggregations describing the current state of the TaskRun table, for monitoring gauges."""

    runs_in_status: list[TaskRunGaugeRow] = Field(default_factory=list)
    oldest_open_age_seconds: list[TaskRunGaugeRow] = Field(default_factory=list)
    created_recently: list[TaskRunGaugeRow] = Field(default_factory=list)
    terminal_recently: list[TaskRunGaugeRow] = Field(default_factory=list)


class ComputeQuotaDenialReason(StrEnum):
    """Why a compute request was refused. The value is the denial code the API returns."""

    COMPUTE_QUOTA_EXHAUSTED = "posthog_code_billing_limit_exceeded"
    ORGANIZATION_DEACTIVATED = "organization_deactivated"


@dataclass(frozen=True, kw_only=True)
class TaskPullRequest:
    url: str
    state: str


@dataclass(frozen=True, kw_only=True)
class LivingArtifactVersionContent:
    name: str
    content_type: str
    content: bytes
    script_sha256: str | None


@dataclass(frozen=True, kw_only=True)
class LivingArtifactVersionPreview:
    name: str
    content_type: str
    script_sha256: str | None


@dataclass(frozen=True, kw_only=True)
class LivingArtifactVersionDownload:
    url: str | None
    error: Literal["not_found", "not_stored", "unavailable"] | None


class SandboxRunStartDenial(StrEnum):
    """Why a task sandbox cannot start a run."""

    NO_ACTOR = "no_actor"
    NESTED = "nested"


@dataclass(frozen=True)
class SandboxRunStarter:
    """The task and run whose sandbox starts a run for the task's owner."""

    parent_task_id: UUID
    parent_run_id: UUID


@dataclass(frozen=True, kw_only=True)
class RunPlan:
    """The user plan a run bills to in place of PostHog credits."""

    plan_name: str
    owner_user_id: int | None