: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import re
import json
import time
import hashlib
import logging
from collections import Counter
from collections.abc import Callable, Collection, Iterable, Iterator, Mapping, Sequence
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field, replace
from datetime import UTC, datetime, timedelta
from functools import partial
from pathlib import PurePosixPath
from typing import TYPE_CHECKING, Any, Literal, TypeVar, cast
from urllib.parse import urlparse
from uuid import UUID, uuid4
from django.conf import settings
from django.core import signing
from django.core.exceptions import (
PermissionDenied,
ValidationError as DjangoValidationError,
)
from django.db import IntegrityError, connection, transaction
from django.db.models import (
BooleanField,
Case,
CharField,
Count,
DateTimeField,
Exists,
F,
Func,
IntegerField,
Max,
Min,
Model,
OuterRef,
Prefetch,
Q,
QuerySet,
Subquery,
TextChoices,
UUIDField,
Value,
When,
)
from django.db.models.fields.json import KeyTextTransform, KeyTransform
from django.db.models.functions import Cast, Coalesce
from django.utils import timezone as django_timezone
from django.utils.dateparse import parse_datetime
from django.utils.http import content_disposition_header
import posthoganalytics
from rest_framework.exceptions import ValidationError
from posthog.api.tagged_item import replace_tags_on_object
from posthog.clickhouse.query_tagging import tag_queries
from posthog.dataclasses import frozen
from posthog.event_usage import groups
from posthog.ingress.contracts import WebhookDelivery
from posthog.integrations import IntegrationManager, IntegrationNotFound, IntegrationRecord
from posthog.models import Team, User
from posthog.models.activity_logging.activity_log import Change, Detail, log_activity
from posthog.models.activity_logging.model_activity import get_was_impersonated
from posthog.models.comment.comment import CANVAS_COMMENT_SCOPES
from posthog.models.integration.codex import CodexAccessGrant, CodexAuthError, CodexReauthRequired, CodexUserIntegration
from posthog.models.oauth import OAuthAccessToken, OAuthRefreshToken
from posthog.temporal.oauth import CONTEXT_LAYER_INTERNAL_SCOPE
from posthog.utils import absolute_uri
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.cdp.backend.facade import api as cdp_facade
from products.posthog_ai.backend.task_ownership import (
detach_conversations_for_task_handoff,
soft_delete_conversations_for_task,
)
from products.tasks.backend.constants import (
AGENT_OTEL_TELEMETRY_STATE_KEY,
ANALYSIS_TARGET_IMAGE_ID_STATE_KEY,
ANALYSIS_TARGET_IMAGE_NAME_STATE_KEY,
ANALYSIS_TARGET_REPOSITORY_STATE_KEY,
ANALYSIS_TARGET_RUN_ID_STATE_KEY,
ANALYSIS_TARGET_TASK_ID_STATE_KEY,
ARTIFACT_SCRIPT_SHA256_KEY as ARTIFACT_SCRIPT_SHA256_KEY,
CI_STATUSES as CI_STATUSES, # re-exported for presentation
CODEX_OWN_SUBSCRIPTION_CLOUD_FEATURE_FLAG as CODEX_OWN_SUBSCRIPTION_CLOUD_FEATURE_FLAG,
DEV_STACK_PREVIEW_PORT,
DEV_STACK_PREVIEW_STATE_KEY,
FINAL_MESSAGE_MAX_CHARS,
GITHUB_PR_URL_PREFIX as GITHUB_PR_URL_PREFIX, # re-exported for signals billing
MAX_CUSTOM_IMAGES_PER_TEAM,
MAX_CUSTOM_IMAGES_PER_USER,
PR_LOOP_ENABLED_STATE_KEY,
PR_STATES as PR_STATES, # re-exported for presentation
RESERVED_SANDBOX_ENVIRONMENT_VARIABLE_KEYS,
SANDBOX_REPOSITORIES_ROOT,
SERVER_OWNED_RESUME_STATE_KEYS,
SUBSCRIPTION_PLAN_NAMES,
TASK_ANALYSIS_ACTIVITIES_STATE_KEY,
TASK_ANALYSIS_FEATURE_FLAG,
TASK_SESSION_MAX_SIZE_BYTES,
TIMED_OUT_INACTIVITY_STATE_KEY as TIMED_OUT_INACTIVITY_STATE_KEY, # re-exported for the scout reaper
get_required_model_flag,
is_blocked_sandbox_env_key,
is_html_artifact as is_html_artifact,
is_same_run_resume_state,
)
from products.tasks.backend.contract_checks import drive_allowed
from products.tasks.backend.error_telemetry import truncate_error_message
from products.tasks.backend.facade.gateway import mint_private_gateway_token, revoke_private_gateway_token
from products.tasks.backend.facade.profiles import (
GithubAccess,
NetworkAccess,
SourceKind,
TaskProfile,
TaskRunOptions,
TaskSource,
resolve_task_origin,
)
from products.tasks.backend.feature_flags import (
get_model_access_error,
own_subscription_cloud_enabled as own_subscription_cloud_enabled,
pi_cloud_runtime_enabled,
run_stream_presence_gated,
)
from products.tasks.backend.github_repository_access import (
inaccessible_repositories_via_integration as _inaccessible_repositories_via_integration,
)
from products.tasks.backend.logic.log_slice import (
LogPart,
LogPartSummary,
log_entries,
slice_log_parts_from,
slice_log_parts_tail,
summarize_log_part,
summary_from_json,
summary_to_json,
)
from products.tasks.backend.logic.model_access import InvalidModelAccess, resolve_model_access
from products.tasks.backend.logic.services.gateway_model_pin import GATEWAY_PRODUCT_STATE_KEY, pinned_run_allows_model
from products.tasks.backend.logic.services.gateway_usage import refresh_task_run_cost
from products.tasks.backend.logic.services.image_builder import (
ensure_image_builder_task,
is_custom_images_enabled,
read_spec_from_builder_sandbox,
)
from products.tasks.backend.logic.services.network_policy import (
MAX_SANDBOX_ALLOWED_DOMAINS,
normalize_requested_domains,
)
from products.tasks.backend.logic.services.sandbox import get_sandbox_class_for_sandbox_id, is_public_sandbox_repo
from products.tasks.backend.logic.services.sandbox_config import MAX_SANDBOX_TTL_SECONDS
from products.tasks.backend.logic.services.space_setup import (
SPACE_SETUP_FEED_EVENT,
SPACE_SETUP_MODEL,
SPACE_SETUP_REASONING_EFFORT,
SPACE_SETUP_RUNTIME_ADAPTER,
SpaceSetupUnavailableError as SpaceSetupUnavailableError,
build_space_setup_prompt,
space_setup_task_title,
)
from products.tasks.backend.logic.services.unattended_plan import (
can_bill_plan_unattended as can_bill_plan_unattended,
unattended_model_access_state as unattended_model_access_state,
)
from products.tasks.backend.logic.services.workflow_step_resume import resume_workflow_step_for_run
from products.tasks.backend.logic.stream.backlog import TaskRunStreamBacklogIndex
from products.tasks.backend.mentions import resolve_mentioned_user_ids
from products.tasks.backend.models import (
MCP_CREDENTIAL_OWNER_STATE_KEY,
PRIOR_RUN_SUMMARY_STATE_KEY,
PRIOR_RUN_TAGS_STATE_KEY,
TASK_OWNERSHIP_VERSION_STATE_KEY,
TASK_RUN_FINISH_REPORT_STATE_KEY,
TASK_RUN_SUMMARY_STATE_KEY,
TASK_RUN_TAGS_STATE_KEY,
Channel,
ChannelContextGeneration,
ChannelFeedMessage,
ChannelInstructions,
ChannelMembership,
ChannelStar,
DesktopBetaTermsAcceptance,
InvalidTaskOriginError,
MCPBuiltInAgentKey,
SandboxCustomImage,
SandboxEnvironment,
SandboxSession,
SandboxSnapshot,
Task,
TaskActivity,
TaskArtifact,
TaskClientProvenance,
TaskCommentActivity,
TaskOwnershipChangedError,
TaskPin,
TaskRun,
TaskSearchDocument,
TaskSession,
TaskThreadMessage,
TaskThreadMessageMention,
TaskWorkflowDispatch,
)
from products.tasks.backend.pr_urls import (
canonical_github_pull_request_url,
merge_pr_output,
normalize_verified_pull_request_urls,
read_head_branches,
read_pr_urls as read_pr_urls,
)
from products.tasks.backend.prompts import build_wizard_pr_agent_prompt, generate_wizard_head_branch
from products.tasks.backend.repository_config_analytics import (
capture_repository_config_changed,
capture_space_context_changed,
repositories_differ,
)
from products.tasks.backend.task_profiles import SPACE_SETUP, USER, WIZARD
from products.tasks.backend.task_sources import apply_task_source, idempotency_key_q, source_q
from products.tasks.backend.visibility import (
PRODUCT_PRIVATE_ORIGIN_PRODUCTS,
TEAM_READABLE_ORIGIN_PRODUCTS,
readable_without_channel,
scout_trial_visibility_q,
task_control_q,
task_run_visibility_q,
task_visibility_q,
)
from . import contracts
from .task_run_signals import hidden_task_ids, task_run_start_refusal
if TYPE_CHECKING:
from products.canvas.backend.facade.contracts import CanvasSummary
logger = logging.getLogger(__name__)
_TASK_LOG_READ_EXECUTOR = ThreadPoolExecutor(max_workers=8, thread_name_prefix="task-log-read")
# --- Enum re-exports ---
# Value types (not ORM models), safe to expose. External callers compare against the
# string-valued ``.status`` / ``.environment`` / ``.origin_product`` fields on the DTOs.
TaskRunStatus = TaskRun.Status
TaskRunEnvironment = TaskRun.Environment
TaskOriginProduct = Task.OriginProduct
TASK_SERVER_ONLY_ORIGIN_PRODUCTS = Task.SERVER_ONLY_ORIGIN_PRODUCTS
TaskRuntime = Task.Runtime
SandboxNetworkAccessLevel = SandboxEnvironment.NetworkAccessLevel
SandboxSnapshotStatus = SandboxSnapshot.Status
# Runtime posture for a setup-wizard cloud run, applied in create_wizard_cloud_run. The model is
# pinned because these runs route to the unbilled `onboarding` gateway product, which allowlists a
# narrow model set; the string form avoids pulling the temporal RuntimeAdapter enum onto this path.
WIZARD_CLOUD_RUN_RUNTIME_ADAPTER = "claude"
WIZARD_CLOUD_RUN_MODEL = "claude-sonnet-5"
WIZARD_CLOUD_RUN_AI_STAGE = "wizard_pr_agent"
class _AutoArchiveUnchanged:
pass
_AUTO_ARCHIVE_UNCHANGED = _AutoArchiveUnchanged()
__all__ = [
"is_current_task_run_actor",
"mint_private_gateway_token",
"revoke_private_gateway_token",
"SandboxNetworkAccessLevel",
"SandboxSnapshotStatus",
"TASK_RUN_SUMMARY_STATE_KEY",
"TASK_SERVER_ONLY_ORIGIN_PRODUCTS",
"TaskOriginProduct",
"TaskRuntime",
"TaskRunEnvironment",
"TaskRunStatus",
"ActiveSessionCapRefused",
"WarmRunActivationUnavailable",
"append_imported_task_run_log",
"append_task_run_log",
"attach_task_run_input_files",
"create_imported_task",
"create_imported_task_run",
"get_imported_task_run",
"get_task_by_origin_key",
"get_task_id_by_idempotency_key",
"touch_imported_task",
"apply_task_run_model_config",
"task_run_model_outside_gateway_pin",
"ensure_task_run_session",
"ensure_subscription_owner",
"get_run_plan",
"own_subscription_cloud_enabled",
"can_bill_plan_unattended",
"unattended_model_access_state",
"beacon_task_presence",
"bootstrap_task_run",
"MAX_SANDBOX_TTL_SECONDS",
"SANDBOX_REPOSITORIES_ROOT",
"can_mint_readonly_github_token",
"is_public_sandbox_repo",
"readonly_github_integration_id",
"check_task_run_startable",
"collect_task_run_state_metrics",
"compute_repository_readiness",
"create_and_run_task",
"get_owner_origin_latest_run",
"owner_origin_has_non_terminal_run",
"owner_origin_open_task_ids",
"owner_origin_recent_task_ids",
"owner_origin_task_ids_with_state_entry",
"create_completed_sandbox_snapshot",
"create_run",
"create_sandbox_connection_token",
"build_sandbox_custom_image",
"create_sandbox_custom_image",
"create_sandbox_environment",
"create_channel_task",
"create_task",
"create_task_without_run",
"create_task_run_connection_token",
"create_task_run_living_artifact",
"create_task_run_stream_read_token",
"resolve_stream_base_url",
"claim_and_fail_stale_run",
"TIMED_OUT_INACTIVITY_STATE_KEY",
"delete_sandbox_custom_image",
"delete_sandbox_environment",
"ensure_personal_channel_id",
"ensure_sandbox_custom_image_builder_task",
"edit_task_run_living_artifact",
"enqueue_comment_activity_retry",
"complete_idle_local_task_run",
"fail_task_run",
"finalize_task_run_artifact_uploads",
"finalize_task_staged_artifacts",
"get_active_wizard_cloud_run",
"get_user_attachment_max_size_bytes",
"get_latest_active_internal_task_run_for_organization",
"get_conversation_task_dtos",
"get_latest_pr_url_by_task",
"get_merged_pr_task_ids",
"get_latest_run_by_task",
"get_resume_snapshot_carry_state",
"get_sandbox_custom_image",
"get_sandbox_environment",
"get_sandbox_snapshot",
"get_stale_prewarmed_queued_task_run_ids",
"get_stale_terminal_prewarmed_task_run_ids",
"get_stale_queued_task_run_ids",
"filter_uncovered_workflow_dispatch_run_ids",
"maintain_workflow_dispatch_outbox",
"get_task_detail",
"task_access_scope",
"normalize_verified_pull_request_urls_batch",
"get_task_id_for_run",
"get_task_run_completed_at",
"get_task_run",
"get_task_run_session",
"sync_task_run_session",
"get_task_run_detail",
"get_task_run_source",
"get_task_run_claude_model_access",
"get_task_run_sandbox_connection",
"resolve_task_run_preview_redirect",
"task_run_preview_ready",
"get_task_run_living_artifact",
"capture_context_wiki_changed",
"capture_relay_command_telemetry",
"PermissionResponseUnavailable",
"validate_permission_response_target",
"classify_permission_response",
"get_task_run_stream_info",
"get_task_summaries",
"is_internal_debug_team",
"is_task_controllable_by_user",
"is_valid_sandbox_env_var_key",
"latest_task_run_pr_merged_subquery",
"latest_task_run_pr_url_subquery",
"leave_task_presence",
"list_sandbox_custom_images",
"list_sandbox_environments",
"sandbox_custom_images_enabled",
"list_task_run_living_artifacts",
"list_task_repositories",
"list_task_run_ids",
"list_task_runs",
"list_tasks",
"list_workflow_last_runs",
"pi_cloud_runtime_enabled",
"prepare_task_run_artifact_uploads",
"prepare_task_staged_artifacts",
"presign_task_run_artifact",
"presign_task_run_artifact_download",
"presign_task_run_living_artifact_version_download",
"read_task_run_artifact",
"read_task_run_html_artifact",
"read_task_run_living_artifact_version",
"sandbox_token_has_open_network",
"is_html_artifact",
"get_task_run_log_urls",
"get_task_run_log_size",
"read_task_run_log_content",
"read_task_run_conversation_logs",
"thread_view_of_log_content",
"read_task_run_conversation_log_slice",
"mark_task_run_stream_watched",
"read_task_run_logs",
"record_comment_activity",
"record_task_mobile_pickup",
"task_mobile_push_taken_over",
"task_mobile_push_delivery_allowed",
"task_mobile_push_user_ids",
"task_mobile_push_suppressed_token_ids",
"enqueue_task_mobile_pr_outcome",
"claim_mobile_push_cooldown",
"release_mobile_push_cooldown",
"record_run_failure_cause",
"signal_task_run_client_activity",
"redispatch_task_run",
"relay_task_run_message",
"resolve_slack_thread_context",
"resume_task_run_in_cloud",
"run_task",
"send_cancel",
"select_repository_for_message",
"set_task_run_output",
"set_task_run_summary",
"set_task_title",
"slack_actor_state_updates",
"signal_report_queryset",
"signal_task_run_user_message",
"signal_workflow_completion",
"soft_delete_task",
"upload_task_run_artifacts",
"start_task_run",
"task_accessible_for_run_view",
"task_channel_id",
"task_exempt_from_code_access",
"task_exists",
"task_ids_with_pr_url_subquery",
"get_pull_requests_for_tasks",
"get_prior_pr_output_by_task",
"read_pr_urls",
"task_run_has_slack_mapping",
"task_run_is_terminal",
"task_run_matches_current_ownership",
"task_runtime",
"task_visible",
"visible_tasks_q",
"task_comment_mentions_allowed",
"list_task_artifacts",
"list_task_comments",
"retrieve_task_comment",
"list_canvas_comments",
"retrieve_canvas_comment",
"update_sandbox_environment",
"update_task",
"update_task_run",
"update_task_run_state",
"upsert_internal_sandbox_env",
"validate_set_output",
"validate_task_run_sandbox_token",
"validate_task_run_artifact_ids",
"warm_task_sandbox",
]
# --- Mappers ---
def _task_to_dto(task: Task) -> contracts.TaskDTO:
return contracts.TaskDTO(
id=task.id,
team_id=task.team_id,
title=task.title,
description=task.description,
origin_product=task.origin_product,
repository=task.repository,
internal=task.internal,
archived=task.archived,
created_at=task.created_at,
updated_at=task.updated_at,
created_by_id=task.created_by_id,
task_number=task.task_number,
slug=task.slug,
)
def _task_run_to_dto(run: TaskRun, *, task: Task | None = None) -> contracts.TaskRunDTO:
"""Map a TaskRun to its DTO.
Pass ``task`` (or rely on a ``select_related("task", "task__created_by")`` queryset)
so the denormalised parent-task fields can be populated without an extra query.
"""
parent = task if task is not None else getattr(run, "task", None)
created_by = getattr(parent, "created_by", None) if parent is not None else None
return contracts.TaskRunDTO(
id=run.id,
task_id=run.task_id,
team_id=run.team_id,
status=run.status,
environment=run.environment,
stage=run.stage,
branch=run.branch,
error_message=run.error_message,
output=run.output,
state=run.state or {},
artifacts=run.artifacts or [],
created_at=run.created_at,
updated_at=run.updated_at,
completed_at=run.completed_at,
is_terminal=run.is_terminal,
workflow_id=run.workflow_id,
mode=run.mode,
task_origin_product=parent.origin_product if parent is not None else None,
task_created_at=parent.created_at if parent is not None else None,
created_by_id=parent.created_by_id if parent is not None else None,
created_by_distinct_id=str(created_by.distinct_id) if created_by is not None else None,
pr_url=(run.output or {}).get("pr_url"),
)
def _hedgehog_config(user: "User") -> dict | None:
"""Mirror core ``UserBasicSerializer.get_hedgehog_config`` so ``created_by`` output is identical."""
config = user.hedgehog_config
if not config:
return None
if config.get("version") == 2:
actor_options = config.get("actor_options", {})
return {
"use_as_profile": config.get("use_as_profile"),
"color": actor_options.get("color"),
"accessories": actor_options.get("accessories"),
"skin": actor_options.get("skin"),
}
return {
"use_as_profile": config.get("use_as_profile"),
"color": config.get("color"),
"accessories": config.get("accessories"),
"skin": config.get("skin"),
}
# The User columns `_user_basic_info` reads; a field read outside this set triggers a
# per-user deferred-load query wherever the queryset restricts to these columns.
_TASK_CREATED_BY_FIELDS = (
"id",
"uuid",
"distinct_id",
"first_name",
"last_name",
"email",
"is_email_verified",
"hedgehog_config",
"role_at_organization",
)
def _user_basic_info(user: "User | None") -> contracts.TaskUserBasicInfo | None:
"""Map a core ``User`` to the display DTO (matches ``UserBasicSerializer`` fields)."""
if user is None:
return None
return contracts.TaskUserBasicInfo(
id=user.id,
uuid=user.uuid,
distinct_id=str(user.distinct_id),
first_name=user.first_name,
last_name=user.last_name,
email=user.email,
is_email_verified=user.is_email_verified,
hedgehog_config=_hedgehog_config(user),
role_at_organization=user.role_at_organization,
)
# Presigned log URLs are cached just under their 1-hour S3 expiry to avoid regeneration.
_TASK_RUN_LOG_URL_CACHE_TTL = 55 * 60
_TASK_RUN_PUBLIC_STATE_KEYS = frozenset(
{
"ai_agent_name",
"ai_stage",
"auto_publish",
"benjamin_enabled",
"claude_model_access",
"claude_subscription_user_id",
"codex_max_subagents",
"codex_model_access",
"codex_shared_prompt_cache",
"codex_subscription_user_id",
"context_window",
"custom_image_id",
"disable_repo_hooks",
"disable_skills",
"fast_mode",
# An imported transcript's provenance and mirror cursor: the viewer marks the run as
# imported, and the legacy mirror reads its own cursor back through this DTO.
"conversation_last_message_id",
"conversation_messages_copied",
"imported_from",
"initial_permission_mode",
"mode",
"model",
"pending_user_artifact_ids",
"pending_user_message",
"pending_user_message_id",
"pr_authorship_mode",
"pr_base_branch",
"prewarmed",
"provider",
"reasoning_effort",
"repositories",
"repository",
"resume_from_run_id",
"rtk_enabled",
"run_source",
"runtime_adapter",
"sandbox_environment_id",
"slack_app_agent_design_enabled",
"slack_artifact_delivery",
"slack_chart_delivery",
"slack_chart_links",
"slack_thread_url",
}
)
# Served only to the run's own task-bound sandbox, which reads them to build the agent's
# first message; without them it silently falls back to `task.description`. Withheld from
# human readers: a workflow task is team-readable, and its boot prompt embeds the triggering
# event wholesale, which for a Slack trigger can be a private channel's message content.
# `end_run_when_done` gates the sandbox's `finish` tool for workflow runs; a key this
# filter drops never reaches the agent server, so the gate would silently do nothing.
# `store_skills` is the acting user's skills-store listing, so it is for their sandbox only.
# `agent_instructions` can carry a member's personal instructions, so the same applies.
_TASK_RUN_AGENT_STATE_KEYS = frozenset(
{
"agent_instructions",
"caller_ends_run",
"end_run_when_done",
"initial_prompt_override",
"store_skills",
"store_skills_bridge",
"systemPrompt",
}
)
def _public_task_run_state(state: dict | None, *, include_agent_keys: bool = False) -> dict:
allowed = _TASK_RUN_PUBLIC_STATE_KEYS
if include_agent_keys:
allowed = allowed | _TASK_RUN_AGENT_STATE_KEYS
return {key: value for key, value in (state or {}).items() if key in allowed}
def _task_run_log_url(run: TaskRun, *, has_analytics_context: bool) -> str | None:
"""Presigned S3 URL for a run's log, cached. Mirrors ``TaskRunDetailSerializer.get_log_url``."""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
from products.tasks.backend.redis import get_tasks_cache # noqa: PLC0415 — keep redis off the api import path
# Protected traces must go through the permission-checked logs endpoint.
if has_analytics_context:
return None
cache_key = f"task_run_log_url:{run.id}"
cached_url = get_tasks_cache().get(cache_key)
if cached_url:
return cached_url
presigned_url = object_storage.get_presigned_url(run.log_url, expiration=3600)
if presigned_url:
get_tasks_cache().set(cache_key, presigned_url, timeout=_TASK_RUN_LOG_URL_CACHE_TTL)
return presigned_url
def _can_read_task_run_summary(
run: TaskRun,
*,
task: Task | None = None,
user_id: int | None = None,
include_agent_state: bool = False,
) -> bool:
if include_agent_state:
return True
parent = task if task is not None else run.task
# A missing viewer never matches, even when the creator was deleted and created_by_id is null.
return parent.origin_product != Task.OriginProduct.WORKFLOW or (
user_id is not None and parent.created_by_id == user_id
)
def _task_run_detail_to_dto(
run: TaskRun,
*,
task: Task | None = None,
include_agent_state: bool = False,
user_id: int | None = None,
include_log_url: bool = True,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> contracts.TaskRunDetailDTO:
"""Map a ``TaskRun`` to its HTTP detail DTO.
Reproduces the SMF-derived fields ``TaskRunDetailSerializer`` computed: ``log_url`` does
presigned-URL I/O (with caching), and ``runtime_adapter`` / ``provider`` / ``model`` /
``reasoning_effort`` are parsed off the run ``state``.
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
parse_run_state,
)
state = parse_run_state(run.state)
has_analytics_context = "analytics_query_context" in (run.state or {})
protected_context = has_analytics_context and not (
include_agent_state
or (analytics_context_reader is not None and analytics_context_reader(run.state["analytics_query_context"]))
)
can_read_summary = _can_read_task_run_summary(
run, task=task, user_id=user_id, include_agent_state=include_agent_state
)
return contracts.TaskRunDetailDTO(
id=run.id,
task=run.task_id,
stage=run.stage,
branch=run.branch,
status=run.status,
environment=run.environment,
runtime_adapter=state.runtime_adapter.value if state.runtime_adapter is not None else None,
provider=state.provider.value if state.provider is not None else None,
model=state.model,
reasoning_effort=state.reasoning_effort.value if state.reasoning_effort is not None else None,
log_url=(
f"/api/projects/{run.team_id}/tasks/{run.task_id}/runs/{run.id}/logs/"
if has_analytics_context and include_agent_state and include_log_url
else _task_run_log_url(run, has_analytics_context=has_analytics_context)
if include_log_url
else None
),
error_message=run.error_message if not protected_context else None,
output=run.output if not protected_context else None,
task_summary=run.task_summary if can_read_summary and not protected_context else None,
task_tags=run.task_tags if can_read_summary and not protected_context else [],
state=_public_task_run_state(run.state, include_agent_keys=include_agent_state),
artifacts=(run.artifacts or []) if not protected_context else [],
created_at=run.created_at,
updated_at=run.updated_at,
completed_at=run.completed_at,
preview_available=task_run_preview_ready(run.state),
scheduled_at=run.scheduled_at,
)
class _LatestRunUnset:
pass
_LATEST_RUN_UNSET = _LatestRunUnset()
class _PriorPrOutputUnset:
pass
_PRIOR_PR_OUTPUT_UNSET = _PriorPrOutputUnset()
# The fields that identify the PR a task points at. A run that opened no PR of its own
# borrows these from the run that did; everything else in an output stays run-local.
_INHERITED_PR_OUTPUT_KEYS = ("pr_url", "pr_urls", "pr_summaries", "pr_state", "pr_merged")
def _inherited_pr_fields(output: object) -> dict[str, Any]:
if not isinstance(output, dict):
return {}
urls = read_pr_urls(output)
if not urls:
return {}
fields = {key: output[key] for key in _INHERITED_PR_OUTPUT_KEYS if key in output}
# An output can carry `pr_urls` without `pr_url`, and some readers look only at the latter
# (the feed's `has_pr` predicate, `get_latest_pr_url_by_task`), so mirror the primary-first
# shape `merge_pr_output` stores.
primary = output.get("pr_url")
if not isinstance(primary, str) or not primary:
primary = urls[0]
fields["pr_url"] = primary
fields["pr_urls"] = [primary, *(url for url in urls if url != primary)]
return fields
def _prior_pr_output_from_runs(task: Task) -> dict[str, Any] | None:
"""The task's most recent PR-carrying run output, taken from the runs already in memory.
Every caller that maps one task prefetches ``runs``, and ``Task.latest_run`` has just walked
them, so the row this needs is loaded — a query for it would be a second trip for rows the
request already holds. Same team scoping and same recency rule as ``Task.latest_run``. The
list path batches its own lookup instead and passes the result in.
"""
pr_runs = [run for run in task.runs.all() if run.team_id == task.team_id and read_pr_urls(run.output)]
if not pr_runs:
return None
return max(pr_runs, key=lambda run: (run.created_at, run.id)).output
def _task_slack_thread_references(task: Task) -> list[contracts.SlackThreadReferenceDTO]:
references: list[contracts.SlackThreadReferenceDTO] = []
for item in (task.state or {}).get("slack_thread_references", []):
if not isinstance(item, dict):
continue
channel = item.get("channel")
thread_ts = item.get("thread_ts")
if not isinstance(channel, str) or not isinstance(thread_ts, str):
continue
references.append(
contracts.SlackThreadReferenceDTO(
url=f"https://slack.com/archives/{channel}/p{thread_ts.replace('.', '')}",
channel=channel,
created_at=item.get("created_at") if isinstance(item.get("created_at"), str) else None,
)
)
return references
def get_task_for_slack_unfurl(task_id: str | UUID, team_id: int, user_id: int) -> contracts.TaskSlackUnfurlDTO | None:
task = (
_visible_task_qs(team_id, user_id)
.filter(id=task_id, internal=False)
.only("id", "title", "created_by_id")
.first()
)
if task is None:
return None
latest_run = task.runs.order_by("-created_at").only("status").first()
return contracts.TaskSlackUnfurlDTO(
id=task.id,
title=task.title,
created_by_id=task.created_by_id,
latest_run_status=latest_run.get_status_display() if latest_run else None,
)
@frozen
class _SlackUnfurlArtifact:
task: Task
run_id: UUID
entry: dict[str, Any]
def _slack_unfurl_artifact_entry(
*,
task_id: str | UUID,
team_id: int,
user_id: int,
run_id: str | UUID | None,
artifact_id: str | None,
name: str | None,
) -> _SlackUnfurlArtifact | None:
"""The downloadable artifact the user may see, by its id or by its file name (newest upload wins).
A run with analytics context is refused. The download endpoint checks the caller's access to
that context against the request, and an unfurl has no request, so it fails closed.
"""
task = _visible_task_qs(team_id, user_id).filter(id=task_id, internal=False).only("id", "title").first()
if task is None or (artifact_id is None and name is None):
return None
runs = TaskRun.objects.filter(team_id=team_id, task_id=task.id)
if run_id is not None:
runs = runs.filter(pk=run_id)
if runs.filter(state__has_key="analytics_query_context").exists():
return None
matches = [
(run_pk, entry)
for run_pk, artifacts in runs.values_list("id", "artifacts")
for entry in artifacts or []
if entry.get("storage_path") and (entry.get("id") == artifact_id if artifact_id else entry.get("name") == name)
]
if not matches:
return None
run_pk, entry = max(matches, key=lambda match: str(match[1].get("uploaded_at") or ""))
return _SlackUnfurlArtifact(task=task, run_id=run_pk, entry=entry)
def get_task_artifact_for_slack_unfurl(
*,
task_id: str | UUID,
team_id: int,
user_id: int,
run_id: str | UUID | None = None,
artifact_id: str | None = None,
name: str | None = None,
) -> contracts.TaskArtifactSlackUnfurlDTO | None:
found = _slack_unfurl_artifact_entry(
task_id=task_id, team_id=team_id, user_id=user_id, run_id=run_id, artifact_id=artifact_id, name=name
)
if found is None:
return None
entry = found.entry
size = entry.get("size")
uploaded_at = entry.get("uploaded_at")
try:
uploaded = datetime.fromisoformat(uploaded_at) if isinstance(uploaded_at, str) else None
except ValueError:
uploaded = None
return contracts.TaskArtifactSlackUnfurlDTO(
name=str(entry.get("name") or "artifact"),
content_type=str(entry.get("content_type") or ""),
size=size if isinstance(size, int) else None,
uploaded_at=uploaded,
task_id=found.task.id,
task_title=found.task.title,
run_id=found.run_id,
artifact_id=str(entry["id"]),
download_path=_artifact_download_path(team_id, found.task.id, found.run_id, str(entry["id"])),
)
def read_task_artifact_for_slack_unfurl(
*,
task_id: str | UUID,
team_id: int,
user_id: int,
max_bytes: int,
run_id: str | UUID | None = None,
artifact_id: str | None = None,
name: str | None = None,
) -> bytes | None:
"""The artifact's bytes, with the same access checks as ``get_task_artifact_for_slack_unfurl``."""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
found = _slack_unfurl_artifact_entry(
task_id=task_id, team_id=team_id, user_id=user_id, run_id=run_id, artifact_id=artifact_id, name=name
)
if found is None:
return None
size = found.entry.get("size")
if not isinstance(size, int) or size > max_bytes:
return None
return object_storage.read_bytes(found.entry["storage_path"], missing_ok=True)
_StateEntryResult = TypeVar("_StateEntryResult")
def read_task_state_entry(task_id: str | UUID, team_id: int, key: str) -> object:
"""One key of the task's shared state bag, or ``None`` when the task or the key is missing."""
state = Task.objects.filter(id=task_id, team_id=team_id).values_list("state", flat=True).first()
return (state or {}).get(key)
def update_task_state_entry(
task_id: str | UUID,
team_id: int,
key: str,
update: Callable[[Any], tuple[Any, _StateEntryResult]],
) -> _StateEntryResult | None:
"""Row-locked read-modify-write of one key in the task's shared state bag.
``update`` gets the current value (``None`` when unset) and returns the value to store and a
result for the caller. Returning the current value unchanged skips the write. Returns ``None``
without calling ``update`` when the task does not exist.
"""
results: list[_StateEntryResult] = []
def _mutate(state: dict[str, Any]) -> None:
current = state.get(key)
value, result = update(current)
results.append(result)
if value != current:
state[key] = value
try:
Task.mutate_state_atomic(task_id, _mutate, team_id=team_id)
except Task.DoesNotExist:
return None
return results[0]
def attach_slack_thread_reference(
*,
task_id: str | UUID,
team_id: int,
slack_workspace_id: str,
channel: str,
thread_ts: str,
shared_by_slack_user_id: str,
) -> None:
reference = {
"slack_workspace_id": slack_workspace_id,
"channel": channel,
"thread_ts": thread_ts,
"shared_by_slack_user_id": shared_by_slack_user_id,
"created_at": django_timezone.now().isoformat(),
}
with transaction.atomic():
task = Task.objects.select_for_update().get(id=task_id, team_id=team_id)
state = dict(task.state or {})
references = list(state.get("slack_thread_references") or [])
if any(
item.get("slack_workspace_id") == slack_workspace_id
and item.get("channel") == channel
and item.get("thread_ts") == thread_ts
for item in references
if isinstance(item, dict)
):
return
references.append(reference)
# Keep a rolling window to bound task state and API response size.
state["slack_thread_references"] = references[-30:]
task.state = state
task.save(update_fields=["state", "updated_at"])
def has_slack_thread_reference(
*, task_id: str | UUID, team_id: int, slack_workspace_id: str, channel: str, thread_ts: str
) -> bool:
task = Task.objects.filter(id=task_id, team_id=team_id).only("state").first()
if task is None:
return False
return any(
item.get("slack_workspace_id") == slack_workspace_id
and item.get("channel") == channel
and item.get("thread_ts") == thread_ts
for item in (task.state or {}).get("slack_thread_references", [])
if isinstance(item, dict)
)
def _task_detail_to_dto(
task: Task,
*,
user_id: int | None = None,
include_latest_run: bool = True,
latest_run: TaskRun | None | _LatestRunUnset = _LATEST_RUN_UNSET,
include_latest_run_log_url: bool = True,
prior_pr_output: dict[str, Any] | None | _PriorPrOutputUnset = _PRIOR_PR_OUTPUT_UNSET,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> contracts.TaskDetailDTO:
"""Map a ``Task`` to its HTTP detail DTO.
``prior_pr_output`` is the task's most recent PR-carrying run output, which backfills
the PR onto ``latest_run`` when that run opened none itself. Callers that map a page of
tasks pass it to keep the lookup to one query; a single task leaves it unset and the
answer comes from the runs that caller already prefetched.
"""
if not include_latest_run:
resolved_latest_run = None
elif isinstance(latest_run, _LatestRunUnset):
resolved_latest_run = task.latest_run
else:
resolved_latest_run = latest_run
latest_run_id = getattr(task, "_latest_run_id", None)
if latest_run_id is None and resolved_latest_run is not None:
latest_run_id = resolved_latest_run.id
latest_run_dto = (
_task_run_detail_to_dto(
resolved_latest_run,
task=task,
user_id=user_id,
include_log_url=include_latest_run_log_url,
analytics_context_reader=analytics_context_reader,
)
if resolved_latest_run is not None
else None
)
may_read_latest_context = (
resolved_latest_run is None
or "analytics_query_context" not in (resolved_latest_run.state or {})
or (
analytics_context_reader is not None
and analytics_context_reader(resolved_latest_run.state["analytics_query_context"])
)
)
if latest_run_dto is not None and may_read_latest_context and not read_pr_urls(latest_run_dto.output):
# A resumed run starts with an empty output, so the PR an earlier run opened drops
# out of `latest_run` — and with it the PR button every client reads from there.
# Logs and artifacts already survive a resume; the PR has to as well.
resolved_prior_pr_output = (
_prior_pr_output_from_runs(task) if isinstance(prior_pr_output, _PriorPrOutputUnset) else prior_pr_output
)
inherited = _inherited_pr_fields(resolved_prior_pr_output)
if inherited:
latest_run_dto = replace(latest_run_dto, output={**(latest_run_dto.output or {}), **inherited})
return contracts.TaskDetailDTO(
id=task.id,
task_number=task.task_number,
slug=task.slug,
title=task.title,
title_manually_set=task.title_manually_set,
description=task.description,
origin_product=task.origin_product,
runtime=task.runtime,
repository=task.repository,
repositories=task.repositories or ([task.repository] if task.repository else []),
github_integration=task.github_integration_id,
github_user_integration=task.github_user_integration_id,
signal_report=task.signal_report_source_id,
json_schema=task.json_schema,
internal=task.internal,
archived=task.archived,
archived_at=task.archived_at,
ci_prompt=task.ci_prompt,
latest_run=latest_run_dto,
created_at=task.created_at,
updated_at=task.updated_at,
last_activity_at=task.last_activity_at or task.updated_at,
created_by=_user_basic_info(task.created_by if task.created_by_id else None),
latest_run_id=latest_run_id,
channel=task.channel_id,
slack_thread_references=_task_slack_thread_references(task),
origin_key=None if task.is_scout_experiment else task.stored_idempotency_key,
client_provenance=task.client_provenance,
)
def _sandbox_env_to_dto(env: SandboxEnvironment) -> contracts.SandboxEnvironmentDTO:
# The names are reported back so a caller can tell which variables are set; the values
# stay server-side. A value that failed to decrypt comes back as its ciphertext string
# rather than a dict, and that is not a variable set, so it reports as none.
env_vars = env.environment_variables if isinstance(env.environment_variables, dict) else {}
return contracts.SandboxEnvironmentDTO(
id=env.id,
team_id=env.team_id,
name=env.name,
network_access_level=env.network_access_level,
private=env.private,
internal=env.internal,
include_default_domains=env.include_default_domains,
allowed_domains=list(env.allowed_domains or []),
repositories=list(env.repositories or []),
effective_domains=env.get_effective_domains(),
has_environment_variables=bool(env_vars),
environment_variable_keys=sorted(env_vars),
created_by=_user_basic_info(env.created_by if env.created_by_id else None),
created_at=env.created_at,
updated_at=env.updated_at,
custom_image_id=env.custom_image_id,
custom_image_name=env.custom_image.name if env.custom_image else None,
custom_image_status=env.custom_image.status if env.custom_image else None,
)
def _sandbox_snapshot_to_dto(snapshot: SandboxSnapshot) -> contracts.SandboxSnapshotDTO:
return contracts.SandboxSnapshotDTO(
id=snapshot.id,
external_id=snapshot.external_id,
status=snapshot.status,
repos=list(snapshot.repos or []),
)
# --- Reads ---
def get_resume_snapshot_carry_state(run_state: dict[str, Any] | None) -> dict[str, Any]:
"""State keys a successor run must merge (whole dict, never ``snapshot_external_id`` alone)
to resume from a prior run's sandbox snapshot; empty when there is no usable snapshot."""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
parse_run_state,
)
return parse_run_state(run_state).resume_snapshot_carry_state()
def get_task_run(run_id: str | UUID, team_id: int | None = None) -> contracts.TaskRunDTO | None:
"""Fetch a single task run as a DTO, optionally scoped to a team."""
qs = TaskRun.objects.select_related("task", "task__created_by")
if team_id is not None:
qs = qs.filter(team_id=team_id)
run = qs.filter(id=run_id).first()
if run is None:
return None
return _task_run_to_dto(run)
def latest_agent_startup_success(*, team_id: int, repository: str, provider: str, runtime: str) -> datetime | None:
started = (
TaskRun.objects.filter(
team_id=team_id,
state__has_key="agent_startup_success",
state__agent_startup_success__repository=repository.lower(),
state__agent_startup_success__provider=provider,
state__agent_startup_success__runtime=runtime,
)
.order_by("-state__agent_startup_success__started_at")
.values_list("state__agent_startup_success__started_at", flat=True)
.first()
)
if not isinstance(started, str):
return None
try:
started_at = parse_datetime(started)
except ValueError:
return None
if started_at is None or django_timezone.is_naive(started_at):
return None
return started_at
def find_signal_implementation_run(
*, team_id: int, repository: str, head_branch: str | None
) -> contracts.SignalImplementationRunDTO | None:
"""The signals-origin implementation run that produced this PR, if any.
Matches the PR's head branch against ``state.self_driving_head_branch``, the branch name the
server generated at run creation (signals' auto_start) and stamped into PATCH-protected run
state. That stamp is the only end of the run->PR link no caller can write: ``output.pr_url``
and ``output.head_branch`` are settable by any team member with task access, so matching on
them would let one member aim the approve-first review carve-out at an App-authored PR whose
contents they chose. The head branch itself comes from GitHub (webhook payload or REST fetch),
so both ends of the join are attested.
Callers (stamphog's inbox carve-out) pass the repository the PR event came from and own fork
safety: pass ``head_branch`` only for a repo-native head, never a fork's (a fork's head ref is
attacker-controlled). Dropping failed and cancelled runs and soft-deleted tasks stops a dead
or disowned run from keeping the carve-out alive on later pushes. A COMPLETED run still
matches: success flips the run to COMPLETED right after it opens the PR, so excluding it
would end re-reviews the moment the implementation finishes.
"""
# TODO(security): the run->PR link is only as strong as the branch NAME, and the name is not a
# secret. state.self_driving_head_branch is unforgeable, but the name it holds is readable by any
# team member (auto_start writes it into the task description, and TaskRunDetailSerializer exposes
# `state`) and low-entropy. A run that finishes WITHOUT opening a PR keeps its stamp yet leaves its
# branch unclaimed, so a member can read the name, have their own task's agent push an App-authored
# repo-native PR from that exact branch, then set_output the original run's pr_url to fire the
# carve-out: the head ref genuinely belongs to this run, so an approve-first review lands on a PR
# whose contents they chose. The real fix is to bind on the head SHA the sandbox actually pushed
# (recorded server-side into protected state) rather than the branch name, because a run that never
# pushed has no SHA to bind, which removes the unclaimed-branch surface entirely; re-reviews then
# pin to the PR identity once the first attested SHA establishes it. It is a heavy change (sandbox
# has to report the pushed SHA back, and the re-review path needs the PR-identity pin), so it is
# deferred. The exposure is intra-tenant and gated behind an opt-in toggle that defaults off, which
# makes it an accepted residual for the current internal rollout; close it before any external one.
if not head_branch:
return None
run = (
TaskRun.objects.filter(
team_id=team_id,
state__self_driving_head_branch=head_branch,
task__repository__iexact=repository.strip(),
task__deleted=False,
)
.exclude(status__in=(TaskRun.Status.FAILED, TaskRun.Status.CANCELLED))
.order_by("-created_at")
.select_related("task")
.first()
)
if run is None or run.team_id != team_id:
return None
task = run.task
# Belt and braces: only signals' auto_start stamps the branch key today, but the ai_stage and
# signal-report checks keep a future writer of the key from silently widening the carve-out.
signal_report_id = task.signal_report_source_id
if signal_report_id is None or (run.state or {}).get("ai_stage") != "implementation":
return None
return contracts.SignalImplementationRunDTO(
run_id=run.id,
task_id=task.id,
team_id=run.team_id,
signal_report_id=signal_report_id,
task_created_by_id=task.created_by_id,
)
def get_wizard_pr_ready_email_context(run_id: str | UUID) -> contracts.WizardPrReadyEmailContextDTO | None:
"""Data ``send_wizard_pr_ready_email`` needs for a run, or ``None`` if the run has no PR URL yet."""
run = TaskRun.objects.select_related("task").filter(id=run_id).first()
if run is None:
return None
pr_url = (run.output or {}).get("pr_url") if isinstance(run.output, dict) else None
if not pr_url:
return None
task = run.task
return contracts.WizardPrReadyEmailContextDTO(
task_id=task.id,
run_id=run.id,
team_id=run.team_id,
origin_product=task.origin_product,
pr_url=pr_url,
repository=task.repository,
branch=run.branch,
created_by_id=task.created_by_id,
already_sent=task.pr_ready_email_sent_at is not None,
)
def mark_task_pr_ready_email_sent(task_id: str | UUID, pr_url: str) -> None:
"""Record confirmed PR-ready email delivery for a task, if it still exists."""
task = Task.objects.filter(id=task_id).first()
if task is not None:
task.mark_pr_ready_email_sent(pr_url)
def get_task_id_for_run(run_id: str | UUID, team_id: int) -> UUID | None:
"""The parent task id for a run, team-scoped. ``None`` if the run isn't found for the team.
A lightweight ``task_run_id -> task_id`` resolution (no DTO build) for callers that only
need to deep-link a run to its task.
"""
return TaskRun.objects.filter(id=run_id, team_id=team_id).values_list("task_id", flat=True).first()
def get_task_run_completed_at(run_ids: Iterable[str | UUID], team_id: int) -> dict[UUID, datetime | None]:
"""Each run's ``completed_at`` by run id, team-scoped. Runs not found for the team are left out.
A primary-key read for callers that only need the completion time, so they skip a join to the
task run table.
"""
return dict(
TaskRun.objects.filter(id__in=list(run_ids), team_id=team_id).order_by().values_list("id", "completed_at")
)
def task_access_scope(*, team_id: int, user: User) -> contracts.TaskAccessScope:
team = Team.objects.get(id=team_id)
access = UserAccessControl(user=user, team=team)
return contracts.TaskAccessScope(
user_id=user.id,
has_resource_access=access.has_resource_access("task"),
allowed_ids=access.allowlisted_resource_ids_by_scope.get("task", frozenset()),
blocked_ids=access.blocked_resource_ids_by_scope.get("task", frozenset()),
)
def normalize_verified_pull_request_urls_batch(
*, team_id: int, after: UUID | None = None, limit: int = 1000
) -> UUID | None:
rows = TaskRun.objects.filter(team_id=team_id, state__has_key="verified_pr_urls").order_by("id")
if after is not None:
rows = rows.filter(id__gt=after)
batch = list(rows.values_list("id", "state")[:limit])
for run_id, state in batch:
verified = state.get("verified_pr_urls") if isinstance(state, dict) else None
if normalize_verified_pull_request_urls(verified) == verified:
continue
def normalize(latest_state: dict[str, Any]) -> None:
latest_state["verified_pr_urls"] = normalize_verified_pull_request_urls(
latest_state.get("verified_pr_urls")
)
TaskRun.mutate_state_atomic(run_id, normalize)
return batch[-1][0] if len(batch) == limit else None
def is_verified_task_pr_url(*, task_id: str | UUID, team_id: int, pr_url: str) -> bool:
"""Whether the GitHub webhook confirmed that a run of this task opened the pull request.
A run's `output.pr_url` is writable through the API. `verified_pr_urls` is server-owned, so a
caller that edits the pull request checks this before it trusts the URL.
"""
verified_url = canonical_github_pull_request_url(pr_url)
verified_filter = Q(state__verified_pr_urls__contains=[pr_url])
if verified_url is not None:
verified_filter |= Q(state__verified_pr_urls__contains=[verified_url])
return TaskRun.objects.filter(verified_filter, task_id=task_id, team_id=team_id).exists()
def task_exists(task_id: str | UUID, team_id: int) -> bool:
"""Whether a (non-deleted) task exists for the team."""
return Task.objects.filter(id=task_id, team_id=team_id, deleted=False).exists()
def task_channel_id(task_id: str | UUID, team_id: int) -> UUID | None:
"""The channel a (non-deleted) task is filed in, or None."""
return Task.objects.filter(id=task_id, team_id=team_id, deleted=False).values_list("channel_id", flat=True).first()
def signal_report_pipeline_stage(task_id: str | UUID, team_id: int) -> str | None:
"""The ``ai_stage`` the Signals report pipeline stamped on this task's runs, or ``None``.
Callers use it to attribute a sandbox agent's writes to the stage that started it. Only
``SIGNAL_REPORT``-origin tasks qualify, and ``ai_stage`` is written server-side once at run
creation (see ``Task.create_and_run``), so the sandbox whose token names the task cannot set
or change it — which is what makes it safe to treat as an identity rather than a claim.
A task's runs all carry the stage the pipeline started it for, so the newest run answers for
the task. ``None`` covers everything else: a scout run, a user-created task, a legacy row
predating the stamp. A person-started Inbox run on a customer-created task carries the
``inbox`` stamp from ``Task.create_run``; it names no pipeline identity, so stage-to-identity
lookups miss it.
"""
state = (
TaskRun.objects.filter(
task_id=task_id,
team_id=team_id,
task__deleted=False,
task__origin_product=Task.OriginProduct.SIGNAL_REPORT,
)
.order_by("-created_at")
.values_list("state", flat=True)
.first()
)
stage = (state or {}).get("ai_stage")
return stage if isinstance(stage, str) and stage else None
def task_owned_by_user(task_id: str | UUID, team_id: int, user_id: int) -> bool:
return Task.objects.filter(id=task_id, team_id=team_id, created_by_id=user_id).exists()
def get_task_creator_ids(task_ids: Iterable[str | UUID], team_ids: Iterable[int]) -> dict[str, int]:
"""The id of the user who started each task, without loading the full task."""
ids = [str(t) for t in task_ids]
teams = list(team_ids)
if not ids or not teams:
return {}
rows = Task.objects.filter(id__in=ids, team_id__in=teams, created_by_id__isnull=False).values_list(
"id", "created_by_id"
)
return {str(task_id): created_by_id for task_id, created_by_id in rows}
def task_exempt_from_code_access(task_id: str | UUID, team_id: int) -> bool:
"""Whether this task's cloud runs are entitled outside PostHog Desktop.
The run/command endpoints gate on Desktop access (``code_access_required_response``) but
also serve the generally-available Inbox, whose tasks must run without the waitlist. Only
server-verifiable Inbox shapes qualify:
- ``SIGNAL_REPORT`` linked to a report in this team, repo-less, and carrying no GitHub
integration (the Inbox "Discuss" fallback). Reports are minted by scouts and the link is
team-scoped by the write serializer, so a caller can't forge one. Acting on a report is
entitled through self-driving (`product-autonomy`). A discussion that resolved a
repository, or that carries the team integration while repo-less, is not exempt under
this shape, because `create_task` only gives it either after the gate passed. Re-checking
here costs the caller nothing.
- ``SIGNALS_CHAT`` (Inbox scout chat), reserved for server-side creation by the signals
scout-chat endpoint; the write serializer rejects it from API callers. Only while
repo-less: chat tasks are minted without repositories, and attaching one via update
would turn the exemption into ungated cloud code work.
- ``SIGNAL_REPORT`` linked to a report in this team that also carries an ``implementation``
``SignalReportTask`` row for this task (the Inbox "Create PR"). Such a task holds a
repository by design, so the repo-less shape above can never cover it. Auto-start opens the
same PR run for the same report from the server without consulting the gate, and
self-driving prices a PR flat and caps it per report, so gating the button would only make
the outcome depend on who started the run. ``record_report_task`` writes the row on both
paths. The relationship label is client input, but it counts only on a row scoped to this
team and to the report the task itself links, so asserting it buys nothing on its own.
A bare ``SIGNAL_REPORT`` origin without a report link deliberately does not qualify:
``origin_product`` is client input, so an FK-less claim would be a one-field waitlist
bypass. The report's own team is re-checked here even though the write serializer
already enforces it, so a future write path can't silently widen the exemption.
"""
linked_report_id = Case(
When(
source_kind=SourceKind.SIGNAL_REPORT.value,
source_id__isnull=False,
then=Cast("source_id", UUIDField()),
),
When(Q(source_kind__isnull=True) | Q(source_id__isnull=True), then=F("signal_report_id")),
output_field=UUIDField(),
)
report_in_team = Exists(signal_report_queryset().filter(id=OuterRef("_linked_report_id"), team_id=team_id))
return (
Task.objects.annotate(_linked_report_id=linked_report_id)
.filter(
Q(
report_in_team,
origin_product=Task.OriginProduct.SIGNAL_REPORT,
repository__isnull=True,
repositories=[],
github_integration__isnull=True,
github_user_integration__isnull=True,
)
| Q(
origin_product=Task.OriginProduct.SIGNALS_CHAT,
repository__isnull=True,
repositories=[],
github_integration__isnull=True,
github_user_integration__isnull=True,
)
| Q(
report_in_team,
origin_product=Task.OriginProduct.SIGNAL_REPORT,
signal_report_tasks__team_id=team_id,
signal_report_tasks__report_id=F("_linked_report_id"),
signal_report_tasks__relationship="implementation",
),
id=task_id,
team_id=team_id,
)
.exists()
)
def get_in_progress_runs_for_github_integration(
team_id: int, integration_id: int, user_id: int | None
) -> contracts.InProgressGithubRunsDTO:
"""In-progress runs whose task uses this team GitHub integration.
Used by core's integration API to block disconnecting a GitHub integration while
live runs still depend on it for credential refresh — deleting the row SET_NULLs
``Task.github_integration`` and permanently orphans every live sandbox's token.
The count covers every run, but the named task is the oldest one ``user_id`` can read.
"""
runs = TaskRun.objects.filter(
team_id=team_id,
status=TaskRun.Status.IN_PROGRESS,
task__github_integration_id=integration_id,
)
count = runs.count()
if not count:
return contracts.InProgressGithubRunsDTO(count=0)
oldest = runs.filter(task_run_visibility_q(user_id)).order_by("created_at").values("task_id", "task__title").first()
if oldest is None:
return contracts.InProgressGithubRunsDTO(count=count)
return contracts.InProgressGithubRunsDTO(
count=count, oldest_task_id=oldest["task_id"], oldest_task_title=oldest["task__title"] or None
)
def is_task_controllable_by_user(task_id: str | UUID, user_id: int | None) -> bool:
"""Whether the user may mutate the task under the task control rules.
Tasks belong to their creator, plus team-wide signal-pipeline tasks and legacy unowned
tasks. Used by core's file-system flow to gate delete/restore on a filed task; public-channel
read visibility deliberately does not qualify.
"""
return Task.objects.filter(task_control_q(user_id), pk=task_id).exists()
def get_sandbox_snapshot(snapshot_id: str | UUID) -> contracts.SandboxSnapshotDTO | None:
"""Fetch a sandbox snapshot as a DTO."""
snapshot = SandboxSnapshot.objects.filter(id=snapshot_id).first()
return _sandbox_snapshot_to_dto(snapshot) if snapshot is not None else None
def get_tasks_by_ids(task_ids: Iterable[str | UUID], team_ids: Iterable[int]) -> list[contracts.TaskDTO]:
"""Tasks matching the supplied ids, restricted to ``team_ids``.
For multi-team callers (e.g. the Slack App Home Tasks card) that already resolved the
set of accessible teams upstream and need a bulk DTO fetch in one query.
"""
ids = [str(t) for t in task_ids]
teams = list(team_ids)
if not ids or not teams:
return []
return [_task_to_dto(task) for task in Task.objects.filter(id__in=ids, team_id__in=teams)]
def get_signal_report_implementation_runs(
team_id: int, report_id: str, task_ids: Iterable[str | UUID]
) -> list[contracts.TaskRunDTO]:
return [
_task_run_to_dto(run)
for run in TaskRun.objects.filter(
source_q(SourceKind.SIGNAL_REPORT, [report_id], via="task__"),
team_id=team_id,
task_id__in=task_ids,
task__team_id=team_id,
task__origin_product=Task.OriginProduct.SIGNAL_REPORT,
task__deleted=False,
)
.select_related("task", "task__created_by")
.order_by("-created_at", "-id")
]
def _pull_request_state(output: Mapping[str, object]) -> str:
"""The state of the PR in ``output.pr_url``. ``pr_merged`` wins over ``pr_state``: it is the
webhook-attested flag, and runs merged before ``pr_state`` existed only carry it."""
if output.get("pr_merged"):
return "merged"
state = output.get("pr_state")
return state if isinstance(state, str) and state in PR_STATES else "unknown"
def get_pull_requests_for_tasks(
team_id: int, task_ids: Iterable[str | UUID], *conditions: Q
) -> dict[str, list[contracts.TaskPullRequest]]:
result: dict[str, list[contracts.TaskPullRequest]] = {}
seen: set[tuple[str, str]] = set()
for task_id, output in (
TaskRun.objects.filter(
*conditions,
team_id=team_id,
task_id__in=task_ids,
)
.order_by("-created_at", "-id")
.values_list("task_id", "output")
):
if not isinstance(output, dict):
continue
for url in read_pr_urls(output):
key = (str(task_id), url)
if key in seen:
continue
seen.add(key)
state = _pull_request_state(output) if url == output.get("pr_url") else "unknown"
result.setdefault(str(task_id), []).append(contracts.TaskPullRequest(url=url, state=state))
return result
def _jsonb_path_exists(path: str) -> Func:
"""``jsonb_path_exists(output, <literal path>)``. The path is always a literal here, so no
caller input reaches the expression."""
return Func("output", Value(path), function="jsonb_path_exists", output_field=BooleanField())
# A run carries a PR when its output yields a usable URL — the rule ``read_pr_urls`` applies in
# Python: a non-empty *string* under ``pr_url``, or any non-empty string in ``pr_urls``. Both
# halves check the JSON type, so SQL selects a run exactly when Python can read a URL out of it.
# Without that, `{"pr_url": 123}` satisfies a bare non-empty test and wins the newest-run pick,
# then Python finds no URL and an older run holding the real PR is never reached. Indexing
# ``pr_urls[0]`` would be wrong for the same reason: it misses ``["", "…/pull/1"]``.
_PR_CARRYING_OUTPUT_Q = Q(_jsonb_path_exists('$.pr_url ? (@.type() == "string" && @ != "")')) | Q(
_jsonb_path_exists('$.pr_urls[*] ? (@.type() == "string" && @ != "")')
)
def get_latest_pr_url_by_task(task_ids: Iterable[str | UUID], *conditions: Q) -> dict[str, str]:
"""Latest usable PR URL per task, for the supplied task ids.
Reads the same normalized shape as everything else: the newest run that carries a PR, and its
primary URL whether the run recorded ``pr_url`` or only ``pr_urls``. Matching ``pr_url`` alone
left a ``pr_urls``-only run with no URL here, which is how Slack App Home lost the link.
"""
ids = [str(t) for t in task_ids]
if not ids:
return {}
rows = (
TaskRun.objects.filter(*conditions, task_id__in=ids)
.filter(_PR_CARRYING_OUTPUT_Q)
.order_by("task_id", "-created_at", "-id")
.distinct("task_id")
.values_list("task_id", "output")
)
urls_by_task = ((str(task_id), read_pr_urls(output)) for task_id, output in rows)
return {task_id: urls[0] for task_id, urls in urls_by_task if urls}
def get_prior_pr_output_by_task(team_id: int, task_ids: Iterable[str | UUID]) -> dict[str, dict[str, Any]]:
"""Most recent run ``output`` that carries a PR, per task.
A run records the PR it opened in its own ``output``. A later run — a resume, a follow-up
message — starts with an empty ``output``, so a reader that sees only the newest run finds
no PR on a task that plainly has one. This supplies the PR that run inherits.
"""
ids = [str(task_id) for task_id in task_ids]
if not ids:
return {}
rows = (
TaskRun.objects.filter(team_id=team_id, task_id__in=ids)
.filter(_PR_CARRYING_OUTPUT_Q)
.order_by("task_id", "-created_at", "-id")
.distinct("task_id")
.values_list("task_id", "output")
)
return {str(task_id): output for task_id, output in rows if isinstance(output, dict)}
def task_ids_with_pr_url_subquery(team_id: int, *conditions: Q) -> QuerySet[TaskRun, Any]:
"""Find same-team tasks with a primary PR or a PR array, including array-only outputs."""
return TaskRun.objects.filter(*conditions, team_id=team_id).filter(_PR_CARRYING_OUTPUT_Q).values("task_id")
def latest_task_run_pr_url_subquery(*conditions: Q, **task_run_filter) -> Subquery:
"""``Subquery`` of the latest non-empty output.pr_url for runs matching the supplied correlation
(keyword lookups and/or positional ``Q`` objects). Returns a query expression to embed in the
caller's queryset — no ORM instances cross the boundary, and the tasks facade stays free of the
caller's domain."""
return Subquery(
TaskRun.objects.filter(*conditions, output__pr_url__isnull=False, **task_run_filter)
.exclude(output__pr_url="")
.order_by("-created_at")
.annotate(output_pr_url_text=KeyTextTransform("pr_url", "output"))
.values("output_pr_url_text")[:1],
output_field=CharField(),
)
def latest_task_run_pr_merged_subquery(*conditions: Q, **task_run_filter) -> Subquery:
"""``Subquery`` of the webhook-attested merge flag on the same run ``latest_task_run_pr_url_subquery``
resolves for the same correlation — so a caller displaying that PR can say whether it merged rather
than inferring it. Same filter and ordering, so the two always describe one run. NULL when no
PR-bearing run matches; treat that as "not merged"."""
return Subquery(
TaskRun.objects.filter(*conditions, output__pr_url__isnull=False, **task_run_filter)
.exclude(output__pr_url="")
.order_by("-created_at")
.annotate(output_pr_merged_flag=KeyTextTransform("pr_merged", "output"))
.values("output_pr_merged_flag")[:1],
output_field=CharField(),
)
def get_merged_pr_task_ids(task_ids: Iterable[str | UUID], *conditions: Q) -> set[str]:
"""Of the supplied tasks, those whose latest PR-bearing run has a webhook-attested merged PR.
Batched counterpart to ``latest_task_run_pr_merged_subquery``, matching ``get_latest_pr_url_by_task``
run-for-run so the merge flag describes the PR URL that helper returns.
"""
ids = [str(t) for t in task_ids]
if not ids:
return set()
rows = (
TaskRun.objects.filter(*conditions, task_id__in=ids, output__pr_url__isnull=False)
.exclude(output__pr_url="")
.order_by("task_id", "-created_at", "-id")
.annotate(output_pr_merged_flag=KeyTextTransform("pr_merged", "output"))
.values("task_id", "output_pr_merged_flag")
.distinct("task_id")
)
return {str(row["task_id"]) for row in rows if row["output_pr_merged_flag"] in ("true", "True")}
def get_latest_run_by_task(task_ids: Iterable[str | UUID]) -> dict[str, contracts.TaskRunDTO]:
"""Most-recent run per task (by ``created_at`` then ``id``), for the supplied task ids."""
ids = [str(t) for t in task_ids]
if not ids:
return {}
runs = (
TaskRun.objects.filter(task_id__in=ids)
.select_related("task", "task__created_by")
.order_by("task_id", "-created_at", "-id")
.distinct("task_id")
)
return {str(run.task_id): _task_run_to_dto(run) for run in runs}
def get_active_wizard_cloud_run(team_id: int) -> contracts.WizardCloudRunDTO | None:
"""The team's active onboarding wizard cloud run, for rehydrating the setup FAB.
The drop flow starts the wizard cloud run server-side (``create_wizard_cloud_run``),
so a freshly-signed-in user has no client-side handle. Returns the most recent run
across the team's onboarding (``ORIGIN_PRODUCT == ONBOARDING``) tasks that's still
running, or completed within the last day (so we can show "PostHog is wired up" +
the PR); otherwise ``None``. Team-scoped.
"""
onboarding_task_ids = Task.objects.filter(
team_id=team_id, origin_product=Task.OriginProduct.ONBOARDING, archived=False
).values_list("id", flat=True)
fresh_after = django_timezone.now() - timedelta(days=1)
# Scan runs newest-first and surface the first that qualifies: picking the newest task up front
# would let a newer onboarding task with no live run hide an older task's still-running one.
# Both the task set and the run are scoped by team_id so a mismatched/legacy run row can't leak
# another team's handle back to the requester.
#
# ``origin_product == ONBOARDING`` is caller-settable, so it alone can't tell a genuine
# server-started wizard run from one a project member planted through the normal task APIs.
# Also require the immutable markers ``create_wizard_cloud_run`` stamps: a cloud environment
# and the ``wizard_config`` state key (a protected key callers cannot set, see the run PATCH
# allowlist), so we never hand a provisioned user someone else's attacker-controlled handle.
runs = TaskRun.objects.filter(
task_id__in=onboarding_task_ids,
team_id=team_id,
environment=TaskRun.Environment.CLOUD,
state__has_key="wizard_config",
).order_by("-created_at", "-id")
for run in runs:
# Non-terminal runs always surface; terminal ones only while the result is still
# fresh enough to be worth showing on first landing.
if run.is_terminal:
anchor = run.updated_at or run.created_at
if anchor is None or anchor < fresh_after:
continue
return contracts.WizardCloudRunDTO(
task_id=run.task_id,
run_id=run.id,
status=run.status,
started_at=run.created_at,
)
return None
def get_latest_internal_task_run_for_organization(
organization_id: str | UUID, *, ai_stage: str, active_only: bool = False, terminal_only: bool = False
) -> contracts.TaskRunDTO | None:
runs = TaskRun.objects.filter(
team__organization_id=organization_id,
task__team__organization_id=organization_id,
task__internal=True,
environment=TaskRun.Environment.CLOUD,
state__ai_stage=ai_stage,
)
if active_only:
runs = runs.filter(
status__in=[
TaskRun.Status.NOT_STARTED,
TaskRun.Status.QUEUED,
TaskRun.Status.IN_PROGRESS,
]
)
if terminal_only:
runs = runs.filter(status__in=_TERMINAL_TASK_RUN_STATUSES)
run = runs.select_related("task", "task__created_by").order_by("-created_at", "-id").first()
return _task_run_to_dto(run) if run is not None else None
def get_latest_active_internal_task_run_for_organization(
organization_id: str | UUID, *, ai_stage: str
) -> contracts.TaskRunDTO | None:
"""Return the newest active cloud run for a server-owned organization flow."""
return get_latest_internal_task_run_for_organization(organization_id, ai_stage=ai_stage, active_only=True)
def get_stale_queued_task_run_ids(
older_than: timedelta,
limit: int,
*,
created_hard_cap: timedelta | None = None,
hard_cap_min_queued: timedelta = timedelta(hours=1),
environment: str | None = None,
exclude_covered_dispatches: bool = False,
) -> list[UUID]:
"""Ids of runs stuck in QUEUED, by ``updated_at`` age or an optional ``created_at`` backstop.
``environment`` restricts the sweep to runs of that environment. A QUEUED cloud run is
awaiting a workflow that should have started, but a local (desktop) run sits in QUEUED by
design while the desktop agent drives it — so sweep callers must scope themselves and act
per environment: dispatch recovery must only touch cloud runs (cloud-dispatching a local
run hijacks the user's live local session), and the janitor fails stale cloud runs but
quietly completes stale local ones.
Intentionally cross-team — the janitor sweep runs without a team context.
"""
now = django_timezone.now()
stale = Q(updated_at__lt=now - older_than)
if created_hard_cap is not None:
stale |= Q(created_at__lt=now - created_hard_cap, updated_at__lt=now - hard_cap_min_queued)
queryset = TaskRun.objects.filter(status=TaskRun.Status.QUEUED) # nosemgrep: celery-task-team-scope-audit
if environment is not None:
queryset = queryset.filter(environment=environment)
if exclude_covered_dispatches:
queryset = queryset.exclude(
workflow_dispatches__status__in=(TaskWorkflowDispatch.Status.PENDING, TaskWorkflowDispatch.Status.CLAIMED)
)
elif environment == TaskRun.Environment.CLOUD:
queryset = queryset.exclude(
workflow_dispatches__status__in=("pending", "claimed"),
workflow_dispatches__enqueued_at__gte=now
- timedelta(seconds=settings.TASKS_DISPATCHER_MAX_DISPATCH_AGE_SECONDS),
)
return list(queryset.filter(stale).order_by("updated_at").values_list("id", flat=True)[:limit])
def filter_uncovered_workflow_dispatch_run_ids(candidate_ids: list[UUID]) -> list[UUID]:
from products.tasks.backend.metrics import WORKFLOW_DISPATCH_MISSING_INTENT_TOTAL # noqa: PLC0415
live_dispatch_run_ids = set(
TaskWorkflowDispatch.objects.unscoped()
.filter(
task_run_id__in=candidate_ids,
status__in=(TaskWorkflowDispatch.Status.PENDING, TaskWorkflowDispatch.Status.CLAIMED),
)
.values_list("task_run_id", flat=True)
)
uncovered_ids = [run_id for run_id in candidate_ids if run_id not in live_dispatch_run_ids]
if not settings.TASKS_WORKFLOW_DISPATCH_OUTBOX_ENABLED:
return uncovered_ids
runs = {
run.id: run
for run in TaskRun.objects.filter(
id__in=uncovered_ids
).select_related( # nosemgrep: celery-task-team-scope-audit
"task"
)
}
dispatch_run_ids = set(
TaskWorkflowDispatch.objects.unscoped()
.filter(task_run_id__in=uncovered_ids)
.values_list("task_run_id", flat=True)
)
for run_id in uncovered_ids:
run = runs.get(run_id)
state = run.state if run and isinstance(run.state, dict) else {}
has_legacy_intent = bool(state.get("pending_dispatch"))
awaiting_restart_rollout = is_same_run_resume_state(state)
if run_id not in dispatch_run_ids and not has_legacy_intent and not awaiting_restart_rollout:
WORKFLOW_DISPATCH_MISSING_INTENT_TOTAL.inc()
logger.warning(
"workflow_dispatch_missing_intent",
extra={
"run_id": str(run_id),
"task_id": str(run.task_id) if run else None,
"team_id": run.team_id if run else None,
"origin_product": run.task.origin_product if run else None,
},
)
return uncovered_ids
def maintain_workflow_dispatch_outbox() -> None:
now = django_timezone.now()
TaskWorkflowDispatch.objects.unscoped().filter(
status=TaskWorkflowDispatch.Status.PENDING,
).exclude(task_run__status=TaskRun.Status.QUEUED).update(
status=TaskWorkflowDispatch.Status.ACCEPTED,
accepted_at=now,
last_error="resolved: run left QUEUED",
)
TaskWorkflowDispatch.objects.unscoped().filter(
status=TaskWorkflowDispatch.Status.CLAIMED,
lease_expires_at__lt=now - timedelta(minutes=10),
).update(
status=TaskWorkflowDispatch.Status.PENDING,
claimed_by="",
lease_expires_at=None,
next_attempt_at=now,
)
accepted_ids = list(
TaskWorkflowDispatch.objects.unscoped()
.filter(status=TaskWorkflowDispatch.Status.ACCEPTED, accepted_at__lt=now - timedelta(days=14))
.order_by("accepted_at")
.values_list("id", flat=True)[:1000]
)
TaskWorkflowDispatch.objects.unscoped().filter(id__in=accepted_ids).delete()
dead_ids = list(
TaskWorkflowDispatch.objects.unscoped()
.filter(status=TaskWorkflowDispatch.Status.DEAD, updated_at__lt=now - timedelta(days=30))
.order_by("updated_at")
.values_list("id", flat=True)[:1000]
)
TaskWorkflowDispatch.objects.unscoped().filter(id__in=dead_ids).delete()
def get_stale_prewarmed_queued_task_run_ids(older_than: timedelta, limit: int) -> list[UUID]:
"""Ids of prewarmed runs orphaned in QUEUED — their processing workflow never started, so the
in-workflow ``WARM_IDLE_TIMEOUT`` (10m) never armed to finalize them.
A live warm run idles in QUEUED awaiting its first message and self-terminates at
``WARM_IDLE_TIMEOUT``, so a prewarmed run still QUEUED well past that window has no workflow
behind it (dispatch lost — e.g. an ``on_commit`` callback that never ran) and can be reaped
immediately rather than lingering until the 24h stale sweep. ``older_than`` should sit safely
above ``WARM_IDLE_TIMEOUT`` so a still-idling warm run is never killed early.
Intentionally cross-team — the janitor sweep runs without a team context.
"""
now = django_timezone.now()
return list(
TaskRun.objects.filter( # nosemgrep: celery-task-team-scope-audit
status=TaskRun.Status.QUEUED,
state__prewarmed=True,
updated_at__lt=now - older_than,
)
.order_by("updated_at")
.values_list("id", flat=True)[:limit]
)
def get_stale_terminal_prewarmed_task_run_ids(older_than: timedelta, limit: int) -> list[UUID]:
now = django_timezone.now()
return list(
TaskRun.objects.filter( # nosemgrep: celery-task-team-scope-audit
status__in=[TaskRun.Status.COMPLETED, TaskRun.Status.FAILED, TaskRun.Status.CANCELLED],
state__prewarmed=True,
state__await_user_message=True,
task__deleted=False,
task__title="",
task__description="",
updated_at__lt=now - older_than,
)
.order_by("updated_at")
.values_list("id", flat=True)[:limit]
)
def _gauge_rows(values_qs, value_key: str, *, with_status: bool, now=None) -> list[contracts.TaskRunGaugeRow]:
rows = []
for row in values_qs:
raw = row[value_key]
value = (now - raw).total_seconds() if now is not None else raw
rows.append(
contracts.TaskRunGaugeRow(
environment=row["environment"],
origin_product=row["origin_product"] or "unknown",
value=value,
status=row["status"] if with_status else None,
)
)
return rows
def collect_task_run_state_metrics(
*,
open_statuses: Sequence[str],
age_statuses: Sequence[str],
terminal_statuses: Sequence[str],
window_seconds: int,
) -> contracts.TaskRunStateMetricsDTO:
"""Aggregate TaskRun state for monitoring gauges.
The caller (a core celery task) owns which statuses count as open/age/terminal and the
recency window; this returns the raw numbers grouped by (status, environment,
origin_product) so no ORM leaks across the boundary.
A QUEUED run's age counts from ``queued_at``, not from row creation:
``prepare_for_cloud_resume`` re-queues an existing run without resetting ``created_at``,
so a cloud restart would otherwise report the whole prior run's lifetime as queue wait.
Rows queued before ``queued_at`` existed fall back to ``created_at``, which is
exact for a run that was only ever queued once. Every other non-terminal status counts
from creation, where elapsed lifetime is the useful age.
"""
now = django_timezone.now()
window_start = now - timedelta(seconds=window_seconds)
age_anchor = Case(
When(status=TaskRun.Status.QUEUED, then=Coalesce(F("queued_at"), F("created_at"))),
default=F("created_at"),
output_field=DateTimeField(),
)
return contracts.TaskRunStateMetricsDTO(
runs_in_status=_gauge_rows(
TaskRun.objects.filter(status__in=open_statuses)
.values("status", "environment", "origin_product")
.annotate(count=Count("id")),
"count",
with_status=True,
),
oldest_open_age_seconds=_gauge_rows(
TaskRun.objects.filter(status__in=age_statuses)
.values("status", "environment", "origin_product")
.annotate(oldest_waiting_since=Min(age_anchor)),
"oldest_waiting_since",
with_status=True,
now=now,
),
created_recently=_gauge_rows(
TaskRun.objects.filter(created_at__gte=window_start)
.values("environment", "origin_product")
.annotate(count=Count("id")),
"count",
with_status=False,
),
terminal_recently=_gauge_rows(
TaskRun.objects.filter(status__in=terminal_statuses)
.annotate(terminal_at=Coalesce(F("completed_at"), F("updated_at"), output_field=DateTimeField()))
.filter(terminal_at__gte=window_start)
.values("status", "environment", "origin_product")
.annotate(count=Count("id")),
"count",
with_status=True,
),
)
# --- Writes ---
def link_slack_task_to_report(*, team_id: int, task_id: str, report_id: str, user_id: int) -> None:
"""Link only a saved Slack task; a repeated activity must not add another discussion entry."""
from products.signals.backend.facade.api import record_slack_report_discussion
with transaction.atomic():
task = Task.objects.select_for_update().get(
team_id=team_id, id=task_id, origin_product=Task.OriginProduct.SLACK, created_by_id=user_id
)
if task.signal_report_source_id is not None:
return
record_slack_report_discussion(team_id=team_id, report_id=report_id, task_id=task_id, user_id=user_id)
task.signal_report_id = UUID(report_id)
task.source_kind = SourceKind.SIGNAL_REPORT.value
task.source_id = str(task.signal_report_id)
task.save(update_fields=["signal_report_id", "source_kind", "source_id", "updated_at"])
def create_and_run_task(
*,
team,
title: str,
description: str,
user_id: int,
origin_product: "Task.OriginProduct | None" = None,
profile: TaskProfile | None = None,
repository: str | None = None,
create_pr: bool = True,
mode: str = "background",
start_workflow: bool = True,
scheduled_at: datetime | None = None,
branch: str | None = None,
signal_report_id: str | None = None,
free_trial_enabled: bool | None = None,
continue_admitted_pipeline: bool = False,
internal: bool | None = None,
sandbox_environment_id: str | None = None,
channel_id: str | UUID | None = None,
source: TaskSource | None = None,
**extra,
) -> contracts.CreatedTaskDTO:
"""Create a task and (optionally) kick off its processing workflow.
Thin wrapper over ``Task.create_and_run`` that returns ids + the created run as a DTO
instead of leaking the ORM ``Task``. ``team`` is a core ``posthog.Team`` (not a tasks
model). Less-common keyword arguments are forwarded verbatim via ``**extra``.
``channel_id`` files the task into a channel's feed; left NULL for non-channel surfaces.
An id the creator can't file into (see ``_visible_channel``) is ignored rather than
raising — feed placement must never break task creation.
``free_trial_enabled`` is a free-trial verdict the caller already resolved. Auto-start reads
that flag before it takes the report row lock, so handing the result over keeps the flag
request out of the lock. Left NULL, the gate reads the flag itself.
``continue_admitted_pipeline`` is for server-side report orchestration after admission.
It lets implementation finish an accepted report/scout pipeline when the spend cap changes.
New manual work leaves it false and checks the quota before creating a run.
``scheduled_at`` creates the run in NOT_STARTED and defers its workflow until the dispatcher
materializes it at or after that time. The run still stores its complete execution settings.
"""
origin = resolve_task_origin(profile=profile, origin_product=origin_product, internal=internal)
origin_product = cast("Task.OriginProduct", origin.origin_product)
internal = origin.internal
columns = apply_task_source(source, signal_report_id=signal_report_id, hog_flow_id=extra.get("hog_flow_id"))
signal_report_id = columns.signal_report_id
if columns.hog_flow_id is not None:
extra["hog_flow_id"] = columns.hog_flow_id
# Research and repository selection continue an admitted pipeline; their caller owns
# admission. Direct implementation creation still needs its own quota check.
if origin_product == Task.OriginProduct.SIGNAL_REPORT and create_pr:
if not continue_admitted_pipeline:
enforce_self_driving_pr_quota(team, report_id=signal_report_id, stage="task_create")
enforce_self_driving_free_trial(
team, report_id=signal_report_id, stage="task_create", enabled=free_trial_enabled
)
channel = _visible_channel(channel_id, team.id, user_id) if channel_id is not None else None
if channel is None and not internal and not readable_without_channel(origin_product, profile):
channel = _ensure_personal_channel(team.id, user_id)[0]
task = Task.create_and_run(
team=team,
title=title,
description=description,
origin_product=origin_product,
profile=profile,
user_id=user_id,
repository=repository,
channel=channel,
create_pr=create_pr,
mode=mode,
start_workflow=start_workflow,
scheduled_at=scheduled_at,
branch=branch,
signal_report_id=signal_report_id,
internal=internal,
sandbox_environment_id=sandbox_environment_id,
**extra,
)
latest = task.latest_run
return contracts.CreatedTaskDTO(
task_id=task.id,
team_id=task.team_id,
latest_run=_task_run_to_dto(latest, task=task) if latest is not None else None,
)
_NON_TERMINAL_RUN_STATUSES = (
TaskRun.Status.NOT_STARTED,
TaskRun.Status.QUEUED,
TaskRun.Status.IN_PROGRESS,
)
def owner_origin_has_non_terminal_run(*, team_id: int, created_by_id: int, origin_product: str) -> bool:
"""Whether this owner already has a run of this origin that has not finished.
Internal origins are hidden from the task APIs, so callers that admit one run at a time
check here instead of listing tasks. ``origin_product`` is required so one product's open
run does not block another's. Soft-deleting a task does not stop its run, so deleted tasks count.
"""
return TaskRun.objects.filter(
team_id=team_id,
task__team_id=team_id,
task__created_by_id=created_by_id,
task__origin_product=origin_product,
status__in=_NON_TERMINAL_RUN_STATUSES,
).exists()
def owner_origin_open_task_ids(*, team_id: int, created_by_id: int, origin_product: str) -> set[UUID]:
"""Ids of this owner's tasks of this origin that have a run that has not finished, deleted tasks included."""
return set(
TaskRun.objects.filter(
team_id=team_id,
task__team_id=team_id,
task__created_by_id=created_by_id,
task__origin_product=origin_product,
status__in=_NON_TERMINAL_RUN_STATUSES,
).values_list("task_id", flat=True)
)
def owner_origin_task_ids_with_state_entry(
*, team_id: int, created_by_id: int, origin_product: str, key: str
) -> set[UUID]:
"""Ids of this owner's tasks of this origin whose shared state holds a non-null ``key``, deleted tasks included."""
return set(
Task.objects.filter(
team_id=team_id,
created_by_id=created_by_id,
origin_product=origin_product,
state__has_key=key,
)
.exclude(state__contains={key: None})
.values_list("id", flat=True)
)
def owner_origin_recent_run_ids(
*, team_id: int, created_by_id: int, origin_product: str, since: datetime, limit: int
) -> list[UUID]:
"""Ids of runs started since ``since`` on this owner's tasks of this origin, newest first, deleted tasks included."""
return list(
TaskRun.objects.filter(
team_id=team_id,
task__team_id=team_id,
task__created_by_id=created_by_id,
task__origin_product=origin_product,
created_at__gte=since,
)
.order_by("-created_at")
.values_list("id", flat=True)[:limit]
)
def owner_origin_recent_task_ids(
*, team_id: int, created_by_id: int, origin_product: str, since: datetime, limit: int
) -> list[UUID]:
"""Ids of this owner's tasks of this origin created since ``since``, newest first. Deleted tasks are left out."""
return list(
Task.objects.filter(
team_id=team_id,
created_by_id=created_by_id,
origin_product=origin_product,
deleted=False,
created_at__gte=since,
)
.order_by("-created_at")
.values_list("id", flat=True)[:limit]
)
def get_owner_origin_latest_run(
*,
task_id: str | UUID,
team_id: int,
created_by_id: int,
origin_product: str,
) -> contracts.TaskRunDTO | None:
"""Latest run of a task, only when team, owner, and origin all match.
A miss on any of those is ``None``. Internal tasks are invisible on the normal task APIs,
so this is the read those products use for their own runs.
"""
try:
task = Task.objects.filter(
id=task_id,
team_id=team_id,
created_by_id=created_by_id,
origin_product=origin_product,
deleted=False,
).first()
except (ValueError, TypeError, DjangoValidationError):
return None
if task is None:
return None
run = task.runs.order_by("-created_at").first()
if run is None:
return None
return _task_run_to_dto(run, task=task)
def create_wizard_cloud_run(
*,
team,
user_id: int,
repository: str,
branch: str | None = None,
) -> contracts.CreatedTaskDTO:
"""Create + run a cloud setup-wizard task.
The workflow runs the published wizard in the sandbox (it integrates PostHog), then the agent
commits the changes, opens a PR on the user's repo, and keeps it green — it never implements
PostHog itself (see the wizard PR agent prompt). The wizard authenticates with its own scoped
token (see ``create_wizard_oauth_access_token``), independent of the agent's sandbox token, so
the agent runs with read-only PostHog scopes.``wizard_config`` marks the run so the workflow runs the wizard pre-agent step.
``user_id`` is the person going through onboarding; it becomes the task's ``created_by`` so the
run is explicitly attributed to them.
The PR head branch is generated here (not by the agent) so the GitHub PR webhook can bind the
opened PR back to this run by branch + repository — wizard PRs are bot-authored, which the
agent-side PR attribution cannot match.
The model is pinned rather than left to the agent's default because these runs bill to nobody:
they route to the unbilled ``onboarding`` gateway product, whose model allowlist is narrow, and
PostHog absorbs the cost. Keep the pin inside that allowlist or the run fails at the gateway.
"""
head_branch = generate_wizard_head_branch()
prompt = build_wizard_pr_agent_prompt(head_branch)
return create_and_run_task(
team=team,
title="Set up PostHog",
description=prompt,
profile=WIZARD,
user_id=user_id,
repository=repository,
options=TaskRunOptions(
adapter=WIZARD_CLOUD_RUN_RUNTIME_ADAPTER, model=WIZARD_CLOUD_RUN_MODEL, mcp_scopes="read_only"
),
create_pr=True,
mode="background",
branch=branch,
wizard_config={},
wizard_head_branch=head_branch,
ai_stage=WIZARD_CLOUD_RUN_AI_STAGE,
# The agent server boots idle; this is the message that actually kicks it off once ready
# (delivered by forward_pending_user_message). Without it the run stalls after "Started agent".
pending_user_message=prompt,
)
def recent_wizard_cloud_run_times(user_id: int, since: datetime) -> list[datetime]:
"""Creation times of a user's recent wizard cloud runs that still count against their quota.
Backs the outcome-aware cloud_run throttles: failed and cancelled runs are excluded so a
user whose run broke (or who cancelled a stuck one) can start another without waiting out
the window. The hard ceiling on total attempts lives in the cloud_run view as an atomic
cache reservation, not here.
The filter trusts only PATCH-immutable markers: ``created_by`` (set at creation) and the
protected ``wizard_config`` state key that only ``create_wizard_cloud_run`` stamps (see
``_PROTECTED_RUN_STATE_KEYS``). The environment is not part of the quota identity because
these immutable markers already identify every wizard cloud run.
Deliberately user-scoped across teams: the throttle is per user, and a user can run the
wizard on projects in different teams. Returns only timestamps, no run data.
"""
return list(
TaskRun.objects.filter(
task__created_by_id=user_id,
state__has_key="wizard_config",
created_at__gte=since,
)
.exclude(status__in=[TaskRun.Status.FAILED, TaskRun.Status.CANCELLED])
.order_by("created_at")
.values_list("created_at", flat=True)
)
def create_task_without_run(
*,
team,
user_id: int,
origin_product: "Task.OriginProduct | None" = None,
profile: TaskProfile | None = None,
title: str = "",
description: str = "",
repository: str | None = None,
mcp_builtin_agent_key: MCPBuiltInAgentKey | None = None,
channel: Channel | None = None,
options: TaskRunOptions | None = None,
source: TaskSource | None = None,
) -> UUID:
"""Create a Task row with no initial run, returning its id.
For callers that own run creation themselves — e.g. the sandbox warm path, which boots the first
run via the warming facade. ``team`` is a core ``posthog.Team`` (not a tasks model).
"""
origin = resolve_task_origin(profile=profile, origin_product=origin_product, internal=None)
if channel is None:
channel = (
None
if readable_without_channel(origin.origin_product, profile)
else _ensure_personal_channel(team.id, user_id)[0]
)
task = Task.create_without_run(
team=team,
title=title,
description=description,
origin_product=cast("Task.OriginProduct", origin.origin_product),
profile=profile,
user_id=user_id,
repository=repository,
channel=channel,
mcp_builtin_agent_key=mcp_builtin_agent_key,
options=options,
source=source,
)
return task.id
def create_channel_task(team_id: int, user_id: int, channel_id: str | UUID, *, title: str, description: str) -> UUID:
"""Create a task filed into a channel, as the user — for product surfaces
(canvas actions) that file work into their own channel. No initial run:
the channel's feed shows it and the user drives it from there.
"""
channel = (
Channel.objects.for_team(team_id).filter(Channel.visible_to_q(user_id), id=channel_id, deleted=False).first()
)
if channel is None:
raise ValueError("Channel not found in this team.")
return create_task_without_run(
team=Team.objects.get(id=team_id),
user_id=user_id,
profile=USER,
title=title,
description=description,
channel=channel,
)
def create_run(
task_id: str | UUID,
*,
mode: str = "background",
extra_state: dict | None = None,
branch: str | None = None,
acting_user_id: int | None = None,
subscription_owner_id: int | None = None,
) -> contracts.TaskRunDTO:
"""Create a new run for an existing task (e.g. resuming an interactive sandbox session).
``acting_user_id`` attributes the run to the user whose AI run preferences should apply
when ``extra_state`` pins no runtime selection; it falls back to the task's creator.
``subscription_owner_id`` names whose plan the run bills to, when that is not the acting user.
"""
task = Task.objects.get(id=task_id)
run = task.create_run(
mode=mode,
extra_state=extra_state,
branch=branch,
acting_user_id=acting_user_id,
subscription_owner_id=subscription_owner_id,
)
return _task_run_to_dto(run, task=task)
def update_task_run_state(
run_id: str | UUID,
*,
updates: dict | None = None,
remove_keys: Iterable[str] | None = None,
) -> dict:
"""Atomically merge state updates into a run's ``state`` and return the new state."""
return TaskRun.update_state_atomic(run_id, updates=updates, remove_keys=remove_keys)
def activate_warm_task_run(run_id: str | UUID) -> None:
warm_runs = TaskRun.objects.filter(id=run_id, state__await_user_message=True)
task_id = warm_runs.values_list("task_id", flat=True).first()
if task_id is None:
return
with transaction.atomic():
task = Task.objects.select_for_update().get(id=task_id)
run = warm_runs.select_for_update(of=("self",)).select_related("task").first()
if run is None:
return
run.state.pop("await_user_message", None)
run.save(update_fields=["state", "updated_at"])
task.observe_run_started_beside_live_runs(run)
def record_run_failure_cause(run_id: str | UUID, error_type: str) -> None:
try:
TaskRun.update_state_atomic(run_id, updates={"failure_error_type": error_type})
except Exception:
logger.warning("Failed to record failure cause for task run %s", run_id, exc_info=True)
def promote_run_to_user_authorship(run_id: str | UUID, actor_user_id: int) -> bool:
"""Promote a bot-authored run to user authorship when the actor now has a usable GitHub install.
Delegates to ``upgrade_run_to_user_authorship``, which persists the change and leaves
runs that are bot-authored by design (signal reports, caller-token runs) untouched.
Returns True when the run was promoted.
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep tasks internals off the api import path
upgrade_run_to_user_authorship,
)
run = TaskRun.objects.select_related("task").filter(id=run_id).first()
actor_user = User.objects.filter(id=actor_user_id).first()
if run is None or actor_user is None:
return False
return upgrade_run_to_user_authorship(run, actor_user, run.state) is not None
def signal_task_run_client_activity(run_id: str | UUID, task_id: str | UUID, team_id: int) -> None:
"""Best-effort: tell the run's workflow a client command landed, so the idle timer resets."""
try:
run = TaskRun.objects.filter(id=run_id, task_id=task_id, team_id=team_id).only("id", "task_id", "state").first()
if run is not None:
run.signal_client_activity()
except Exception:
logger.warning("Failed to signal client activity for task run %s", run_id)
def slack_actor_state_updates(*, user_id: int, slack_user_id: str | None = None) -> dict[str, Any]:
"""Run-state updates recording the Slack user currently steering a run.
Credential resolution and reply tagging read the keys this builds, so every
writer must go through here rather than assembling the dict inline.
"""
from products.tasks.backend.logic.services.run_actor import ( # noqa: PLC0415 — keep tasks internals off the api import path
slack_actor_state_updates as _slack_actor_state_updates,
)
return _slack_actor_state_updates(user_id=user_id, slack_user_id=slack_user_id)
def set_task_run_created_at_for_seeding(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, created_at: datetime
) -> None:
"""Backdate a run's ``created_at`` — DEBUG-only escape hatch for dev seeding.
Signals' billing/refund seeding needs runs whose billable moment falls on an earlier UTC
day; ``created_at`` is deliberately not writable through the PATCH surface, so the hatch
lives here rather than callers reaching into the ORM.
"""
if not settings.DEBUG:
raise RuntimeError("set_task_run_created_at_for_seeding is DEBUG-only")
TaskRun.objects.filter(pk=run_id, task_id=task_id, team_id=team_id).update(created_at=created_at)
def fail_task_run(run_id: str | UUID, error: str, error_type: str | None = None) -> bool:
"""Mark a QUEUED run as failed. Returns whether a run was acted on.
Refetches filtered on ``status=QUEUED`` so a run that left the queue between the
candidate scan and this call is skipped. Intentionally cross-team (janitor sweep).
"""
run = TaskRun.objects.filter(
pk=run_id, status=TaskRun.Status.QUEUED
).first() # nosemgrep: celery-task-team-scope-audit
if run is None:
return False
run.mark_failed(error, error_type=error_type)
run.task.soft_delete_if_unclaimed_prewarm(run)
return True
def soft_delete_unclaimed_prewarm_task(run_id: str | UUID) -> bool:
run = TaskRun.objects.select_related("task").filter(pk=run_id).first() # nosemgrep: celery-task-team-scope-audit
return run.task.soft_delete_if_unclaimed_prewarm(run) if run is not None else False
def complete_idle_local_task_run(run_id: str | UUID) -> bool:
"""Quietly finalize a local (desktop-driven) run left idling in QUEUED. Returns whether
a run was acted on.
Local runs never get a cloud workflow, so QUEUED is their steady state while the desktop
drives the session — once the desktop goes away, nothing else ever terminalizes the row.
An idle session that ended is the run's normal end state, so it finalizes as COMPLETED,
and without a push notification: pinging a user a day after they closed their session is
noise, not signal.
Compare-and-set claim (like ``claim_and_fail_stale_run``): the conditional update flips the
run only while it is still QUEUED *and* local, so a run that left the queue between the
candidate scan and this call is skipped. The winner finalizes
via ``mark_completed`` (``completed_at``, stream + analytics). Intentionally cross-team
(janitor sweep).
"""
claimed = TaskRun.objects.filter(
pk=run_id, status=TaskRun.Status.QUEUED, environment=TaskRun.Environment.LOCAL
).update(status=TaskRun.Status.COMPLETED) # nosemgrep: celery-task-team-scope-audit
if not claimed:
return False
run = TaskRun.objects.filter(pk=run_id).first() # nosemgrep: celery-task-team-scope-audit
if run is not None:
run.mark_completed(notify=False, analytics_properties={"finalized_by": "stale_local_queued_sweep"})
_observe_claimed_terminal(run, error_type=None)
return True
def claim_and_fail_stale_run(run_id: str | UUID, error: str, error_type: str | None = None) -> bool:
"""Compare-and-set reap of a stranded run. Returns whether this caller won the claim.
Atomically flips a run still in ``QUEUED``/``IN_PROGRESS`` to ``FAILED`` via a conditional
update, so concurrent reapers of the same row resolve to exactly one winner (the losers match
zero rows). The winner finalizes via ``mark_failed`` (error message, ``completed_at``, stream +
analytics). Intentionally cross-team (janitor sweep).
"""
claimed = TaskRun.objects.filter(
id=run_id,
status__in=(TaskRun.Status.QUEUED, TaskRun.Status.IN_PROGRESS),
).update(status=TaskRun.Status.FAILED) # nosemgrep: celery-task-team-scope-audit
if not claimed:
return False
run = TaskRun.objects.filter(pk=run_id).first() # nosemgrep: celery-task-team-scope-audit
if run is not None:
run.mark_failed(error, error_type=error_type)
_observe_claimed_terminal(run, error_type=error_type)
resume_workflow_step_for_run(run)
return True
def _observe_claimed_terminal(run: TaskRun, *, error_type: str | None) -> None:
# The conditional update already wrote the terminal status, so mark_* sees a terminal run and
# skips its own count. The claim winner counts the transition here instead.
from products.tasks.backend.metrics import ( # noqa: PLC0415 — keep prometheus deps off the api import path
observe_task_run_terminal,
)
observe_task_run_terminal(run, error_type=error_type, termination_reason=None)
def redispatch_task_run(run_id: str | UUID) -> str:
"""Re-dispatch a QUEUED run whose create-time workflow dispatch was lost. Cross-team janitor call.
Idempotent recover-only wrapper over the temporal client — never fails the run. Returns the
outcome (``recovered`` / ``already_running`` / ``left_queue`` / ``error``).
"""
from products.tasks.backend.temporal.client import ( # noqa: PLC0415 — keep temporalio off the api import path
redispatch_orphaned_task_run,
)
return redispatch_orphaned_task_run(str(run_id))
def upsert_internal_sandbox_env(
team_id: int,
name: str,
network_access_level: "SandboxEnvironment.NetworkAccessLevel",
*,
private: bool = False,
internal: bool = True,
allowed_domains: list[str] | None = None,
include_default_domains: bool = False,
) -> UUID:
"""Get-or-create an internal sandbox environment, reasserting policy on every call.
Only rows already carrying the requested ``internal`` flag are matched for reuse: users
can create environments with arbitrary names through the sandbox environment API, and a
same-named user row must never be adopted (or deleted) by internal provisioning — the
internal env is created alongside it instead. Reasserted policy covers the whole
execution surface, not just network: the user-controllable ``custom_image``,
``environment_variables``, and ``repositories`` fields are cleared on every call, so
nothing a person set on a row (before or after it became internal) can ride into an
internally provisioned run.
``SandboxEnvironment`` has no unique constraint on ``(team_id, name)``. A transaction-scoped
advisory lock on ``(team_id, name, internal)`` serializes concurrent callers, so they cannot
both INSERT. Without it, a dedupe could delete a row that another caller already returned.
Duplicates from before the lock are still deduped: we keep the oldest matching row and
delete the rest.
"""
defaults: dict = {
"network_access_level": network_access_level,
"private": private,
"custom_image": None,
"environment_variables": {},
"repositories": [],
}
if allowed_domains is not None:
defaults["allowed_domains"] = normalize_sandbox_allowed_domains(allowed_domains)
defaults["include_default_domains"] = include_default_domains
with transaction.atomic():
with connection.cursor() as cursor:
cursor.execute(
"SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
[team_id, f"internal-sandbox-env:{internal}:{name}"],
)
try:
env, _ = SandboxEnvironment.objects.update_or_create(
team_id=team_id, name=name, internal=internal, defaults=defaults
)
return env.id
except SandboxEnvironment.MultipleObjectsReturned:
dupes = list(
SandboxEnvironment.objects.filter(team_id=team_id, name=name, internal=internal).order_by("created_at")
)
keeper = dupes[0]
SandboxEnvironment.objects.filter(id__in=[d.id for d in dupes[1:]]).delete()
for key, value in defaults.items():
setattr(keeper, key, value)
keeper.save(update_fields=list(defaults.keys()))
return keeper.id
def create_completed_sandbox_snapshot(external_id: str) -> UUID:
"""Record a completed sandbox snapshot for an externally-built image; return its id."""
snapshot = SandboxSnapshot.objects.create(external_id=external_id, status=SandboxSnapshot.Status.COMPLETE)
return snapshot.id
def get_desktop_beta_terms_acceptance(organization_id: UUID) -> contracts.DesktopBetaTermsAcceptanceDTO:
return contracts.DesktopBetaTermsAcceptanceDTO(
is_desktop_beta_terms_accepted=DesktopBetaTermsAcceptance.objects.filter(
organization_id=organization_id
).exists()
)
def accept_desktop_beta_terms(organization_id: UUID, user_id: int) -> contracts.DesktopBetaTermsAcceptanceDTO:
DesktopBetaTermsAcceptance.objects.get_or_create(
organization_id=organization_id,
defaults={"accepted_by_user_id": user_id},
)
return contracts.DesktopBetaTermsAcceptanceDTO(is_desktop_beta_terms_accepted=True)
def revoke_desktop_beta_terms(organization_id: UUID, user: User) -> contracts.DesktopBetaTermsAcceptanceDTO:
with transaction.atomic():
acceptance = DesktopBetaTermsAcceptance.objects.filter(organization_id=organization_id).first()
if acceptance is not None:
acceptance.delete()
# The deleted row is the only record of who accepted and when, so the audit entry keeps both.
log_activity(
organization_id=organization_id,
team_id=None,
user=user,
was_impersonated=get_was_impersonated(),
item_id=organization_id,
scope="Organization",
activity="updated",
detail=Detail(
changes=[
Change(
type="Organization",
action="revoked",
field="PostHog Desktop beta terms",
before={
"accepted_by_user_id": acceptance.accepted_by_user_id,
"accepted_at": acceptance.accepted_at.isoformat(),
},
after=None,
)
]
),
)
return contracts.DesktopBetaTermsAcceptanceDTO(is_desktop_beta_terms_accepted=False)
# --- Sandbox environments (presentation CRUD) ---
# Visibility: an environment is reachable by a team member if it is non-private, or it is
# theirs (``created_by``). ``list`` additionally hides ``internal`` environments.
def is_valid_sandbox_env_var_key(key: str) -> bool:
"""Whether ``key`` is a valid environment-variable name (``[A-Za-z_][A-Za-z0-9_]*``)."""
return SandboxEnvironment.is_valid_env_var_key(key)
def is_blocked_sandbox_env_var_key(key: str) -> bool:
return is_blocked_sandbox_env_key(key)
def is_reserved_sandbox_env_var_key(key: str) -> bool:
return key in RESERVED_SANDBOX_ENVIRONMENT_VARIABLE_KEYS
def _validate_user_sandbox_env_vars(environment_variables: dict | None) -> None:
for key in environment_variables or {}:
if not SandboxEnvironment.is_valid_env_var_key(key):
raise ValueError(f"Invalid environment variable key: {key!r}")
if is_blocked_sandbox_env_key(key) or key in RESERVED_SANDBOX_ENVIRONMENT_VARIABLE_KEYS:
raise ValueError(f"Environment variable key {key!r} is not allowed")
def normalize_sandbox_allowed_domains(allowed_domains: list[str]) -> list[str]:
if len(allowed_domains) > MAX_SANDBOX_ALLOWED_DOMAINS:
raise ValueError(f"You can allow up to {MAX_SANDBOX_ALLOWED_DOMAINS} domains")
return list(normalize_requested_domains(allowed_domains))
def _accessible_sandbox_envs(team_id: int, user_id: int):
return (
SandboxEnvironment.objects.filter(team_id=team_id)
.filter(Q(private=False) | Q(created_by_id=user_id))
.select_related("created_by", "custom_image")
)
def list_sandbox_environments(team_id: int, user_id: int) -> list[contracts.SandboxEnvironmentDTO]:
"""Non-internal environments visible to the user, for the list view."""
return [_sandbox_env_to_dto(env) for env in _accessible_sandbox_envs(team_id, user_id).filter(internal=False)]
def get_sandbox_environment(env_id: str | UUID, team_id: int, user_id: int) -> contracts.SandboxEnvironmentDTO | None:
"""A single environment visible to the user (internal ones are retrievable by id)."""
env = _accessible_sandbox_envs(team_id, user_id).filter(pk=env_id).first()
return _sandbox_env_to_dto(env) if env is not None else None
def _validate_custom_image_id(team_id: int, user_id: int, custom_image_id: str | UUID | None) -> None:
if custom_image_id is None:
return
if not sandbox_custom_images_enabled(team_id, user_id):
raise ValueError("Custom sandbox images require the Modal VM runtime, which is not enabled")
image = SandboxCustomImage.get_accessible_for_task(
image_id=custom_image_id, team_id=team_id, task_created_by_id=user_id
)
if image is None:
raise ValueError(f"Invalid custom_image_id: {custom_image_id}")
def create_sandbox_environment(
team_id: int,
user_id: int,
*,
name: str,
network_access_level: str,
allowed_domains: list[str],
include_default_domains: bool,
repositories: list[str],
environment_variables: dict,
private: bool,
custom_image_id: str | None = None,
) -> contracts.SandboxEnvironmentDTO:
"""Create a team environment owned by the user and return it as a DTO."""
_validate_user_sandbox_env_vars(environment_variables)
_validate_custom_image_id(team_id, user_id, custom_image_id)
normalized_allowed_domains = normalize_sandbox_allowed_domains(allowed_domains)
env = SandboxEnvironment.objects.create(
team_id=team_id,
created_by_id=user_id,
name=name,
network_access_level=network_access_level,
allowed_domains=normalized_allowed_domains,
include_default_domains=include_default_domains,
repositories=repositories,
environment_variables=environment_variables,
private=private,
custom_image_id=custom_image_id,
)
return _sandbox_env_to_dto(SandboxEnvironment.objects.select_related("created_by", "custom_image").get(pk=env.pk))
def update_sandbox_environment(
env_id: str | UUID, team_id: int, user_id: int, **fields
) -> contracts.SandboxEnvironmentDTO | None:
"""Partially update a visible environment. Returns ``None`` if not found/visible."""
env = _accessible_sandbox_envs(team_id, user_id).filter(pk=env_id).first()
if env is None:
return None
if "environment_variables" in fields:
_validate_user_sandbox_env_vars(fields["environment_variables"])
if "custom_image_id" in fields:
_validate_custom_image_id(team_id, user_id, fields["custom_image_id"])
if "allowed_domains" in fields:
fields["allowed_domains"] = normalize_sandbox_allowed_domains(fields["allowed_domains"])
for key, value in fields.items():
setattr(env, key, value)
env.save()
return _sandbox_env_to_dto(SandboxEnvironment.objects.select_related("created_by", "custom_image").get(pk=env.pk))
def delete_sandbox_environment(env_id: str | UUID, team_id: int, user_id: int) -> bool:
"""Delete a visible environment. Returns whether a row was deleted."""
env = _accessible_sandbox_envs(team_id, user_id).filter(pk=env_id).first()
if env is None:
return False
env.delete()
return True
# --- Sandbox custom images (presentation CRUD + builder/build flows) ---
def sandbox_custom_images_enabled(team_id: int, user_id: int, origin_product: str | None = None) -> bool:
"""Whether custom base images are available for this team (Modal VM runtime flag gate)."""
team = Team.objects.only("id", "organization_id").get(id=team_id)
user = User.objects.only("id", "distinct_id").get(id=user_id)
return is_custom_images_enabled(
distinct_id=user.distinct_id or f"user-{user_id}",
organization_id=str(team.organization_id),
origin_product=origin_product,
)
def _custom_image_to_dto(
image: SandboxCustomImage, *, include_build_log: bool = False
) -> contracts.SandboxCustomImageDTO:
from products.tasks.backend.logic.services.image_spec import spec_json_to_yaml # noqa: PLC0415
return contracts.SandboxCustomImageDTO(
id=image.id,
team_id=image.team_id,
name=image.name,
description=image.description,
repository=image.repository,
private=image.private,
status=image.status,
version=image.version,
modal_image_name=image.modal_image_name,
error=image.error,
spec=image.spec or {},
spec_yaml=spec_json_to_yaml(image.spec or {}),
scan_result=image.scan_result or {},
build_log=image.build_log if include_build_log else "",
builder_task_id=image.builder_task_id,
created_by=_user_basic_info(image.created_by if image.created_by_id else None),
created_at=image.created_at,
updated_at=image.updated_at,
)
def _accessible_custom_images(team_id: int, user_id: int):
return (
SandboxCustomImage.objects.filter(team_id=team_id)
.filter(Q(private=False) | Q(created_by_id=user_id))
.select_related("created_by")
)
def _reload_image_dto(image_pk: UUID) -> contracts.SandboxCustomImageDTO:
return _custom_image_to_dto(SandboxCustomImage.objects.select_related("created_by").get(pk=image_pk))
def list_sandbox_custom_images(team_id: int, user_id: int) -> list[contracts.SandboxCustomImageDTO]:
"""Non-archived custom images visible to the user, newest first."""
images = (
_accessible_custom_images(team_id, user_id)
.exclude(status=SandboxCustomImage.Status.ARCHIVED)
.order_by("-created_at")
)
return [_custom_image_to_dto(image) for image in images]
def get_sandbox_custom_image(
image_id: str | UUID, team_id: int, user_id: int
) -> contracts.SandboxCustomImageDTO | None:
"""Single-image detail; the only read that includes the (potentially large) build log."""
image = _accessible_custom_images(team_id, user_id).filter(id=image_id).first()
return _custom_image_to_dto(image, include_build_log=True) if image is not None else None
def create_sandbox_custom_image(
team_id: int,
user_id: int,
*,
name: str,
description: str = "",
repository: str | None = None,
private: bool = False,
) -> contracts.SandboxCustomImageDTO:
"""Create a draft custom image and dispatch its interactive image-builder agent task."""
from products.tasks.backend.logic.services.image_spec import validate_image_repository # noqa: PLC0415
if repository:
validate_image_repository(repository)
counts = (
SandboxCustomImage.objects.filter(team_id=team_id)
.exclude(status=SandboxCustomImage.Status.ARCHIVED)
.aggregate(team=Count("id"), user=Count("id", filter=Q(created_by_id=user_id)))
)
if counts["team"] >= MAX_CUSTOM_IMAGES_PER_TEAM:
raise ValueError(f"This team already has {MAX_CUSTOM_IMAGES_PER_TEAM} custom images; delete one first")
if counts["user"] >= MAX_CUSTOM_IMAGES_PER_USER:
raise ValueError(f"You already have {MAX_CUSTOM_IMAGES_PER_USER} custom images; delete one first")
image = SandboxCustomImage.objects.create(
team_id=team_id,
created_by_id=user_id,
name=name,
description=description,
repository=repository or "",
private=private,
)
ensure_image_builder_task(image, user_id)
return _reload_image_dto(image.pk)
def ensure_sandbox_custom_image_builder_task(
image_id: str | UUID, team_id: int, user_id: int
) -> contracts.SandboxCustomImageDTO | None:
"""Revive (or reuse) the image's builder session; new sessions are seeded with the stored spec."""
image = _accessible_custom_images(team_id, user_id).filter(id=image_id).first()
if image is None:
return None
ensure_image_builder_task(image, user_id)
return _reload_image_dto(image.pk)
def build_sandbox_custom_image(
image_id: str | UUID, team_id: int, user_id: int, *, spec_yaml: str | None = None
) -> contracts.SandboxCustomImageDTO | None:
"""Persist the image spec and kick off the scan → build → publish workflow.
The spec comes from ``spec_yaml`` when provided, otherwise it is read from the
builder task's live sandbox. Raises ``ValueError`` on an invalid or empty spec.
"""
from products.tasks.backend.logic.services.image_spec import ( # noqa: PLC0415
SandboxImageSpecError,
parse_image_spec_json,
parse_image_spec_yaml,
validate_spec_buildable,
)
from products.tasks.backend.metrics import (
observe_custom_image_build, # noqa: PLC0415 — keep prometheus deps off the api import path
)
from products.tasks.backend.temporal.client import execute_build_sandbox_image_workflow # noqa: PLC0415
image = _accessible_custom_images(team_id, user_id).filter(id=image_id).first()
if image is None:
return None
if image.status in (SandboxCustomImage.Status.SCANNING, SandboxCustomImage.Status.BUILDING):
raise ValueError("A build is already in progress for this image")
try:
spec = parse_image_spec_yaml(spec_yaml) if spec_yaml is not None else read_spec_from_builder_sandbox(image)
except SandboxImageSpecError as e:
# Builder sandbox gone → the stored spec is the only correct rebuild source.
if spec_yaml is None and image.spec:
spec = parse_image_spec_json(image.spec)
else:
raise ValueError(str(e))
if spec.is_empty:
raise ValueError("The image spec is empty; add packages, commands, or env vars before building")
validate_spec_buildable(spec, image.repository)
updated = (
_accessible_custom_images(team_id, user_id)
.filter(id=image.id)
.exclude(status__in=(SandboxCustomImage.Status.SCANNING, SandboxCustomImage.Status.BUILDING))
.update(
spec=spec.model_dump(),
status=SandboxCustomImage.Status.SCANNING,
error="",
updated_at=django_timezone.now(),
)
)
if not updated:
raise ValueError("A build is already in progress for this image")
observe_custom_image_build("started")
execute_build_sandbox_image_workflow(str(image.id), team_id)
return _reload_image_dto(image.pk)
def update_sandbox_custom_image(
image_id: str | UUID,
team_id: int,
user_id: int,
*,
name: str | None = None,
description: str | None = None,
) -> contracts.SandboxCustomImageDTO | None:
"""Rename (and optionally re-describe) a visible custom image.
Only mutable metadata (`name`, `description`) is editable here — the build spec,
status, and published image reference are managed by the build/scan flow. Returns
``None`` when the image is not visible to the caller.
"""
updates: dict[str, str] = {}
if name is not None:
updates["name"] = name
if description is not None:
updates["description"] = description
if not updates:
return get_sandbox_custom_image(image_id, team_id, user_id)
updated = (
_accessible_custom_images(team_id, user_id)
.filter(id=image_id)
.update(**updates, updated_at=django_timezone.now())
)
if not updated:
return None
# Re-read through get_sandbox_custom_image rather than _reload_image_dto: if a
# concurrent delete removes the row between the update above and this read,
# `.first()` returns None (→ 404) instead of .get() raising DoesNotExist (→ 500).
return get_sandbox_custom_image(image_id, team_id, user_id)
def delete_sandbox_custom_image(image_id: str | UUID, team_id: int, user_id: int) -> bool:
"""Delete a visible custom image. Environments referencing it fall back to the default base (SET_NULL)."""
image = _accessible_custom_images(team_id, user_id).filter(id=image_id).first()
if image is None:
return False
image.delete()
return True
# --- Task runs (presentation lifecycle) ---
# Every function takes ids/primitives and returns a TaskRunDetailDTO (or a small result),
# moving all ORM access and Temporal/Slack/S3 orchestration behind the facade. Visibility on
# the parent task is enforced via ``task_visibility_q``; runs are always team-scoped.
# Run-state keys that are server-owned and must never be mutable through the PATCH endpoint:
# - github_credential_source / pr_authorship_mode fix the run's GitHub identity at creation;
# a caller could otherwise flip a caller-token run to ``server_integration`` and have the
# task creator's server-side token injected into their sandbox.
# - sandbox_id is the credential-propagation target; a caller could otherwise repoint a visible
# run at a sandbox they control and capture the run owner's token on the next rotation.
# - sandbox_cpu_cores / sandbox_memory_gb / sandbox_ttl_seconds / inactivity_timeout_seconds set
# the run's compute and lifetime at creation; a caller could otherwise PATCH a queued run to
# provision an oversized or long-lived sandbox beyond what they're entitled to.
# - use_modal_vm_sandbox is reserved for trusted server-created runs such as image builders;
# a caller could otherwise force the VM runtime while the feature flag or custom-image gate is off.
# - snapshot_external_id / snapshot_kind / snapshot_mount_path control which Modal image is
# restored on resume and where directory snapshots are mounted.
# - same-run resume markers control whether provisioning reloads the current run's logs and
# starts the sandbox idle. Legacy marker names remain protected during rollout.
# - workflow_id is the run's Temporal workflow address (``TaskRun.workflow_id`` prefers it over
# the derived id); a caller could otherwise repoint their run at another team's workflow and
# signal or terminate-and-restart it.
# - pending_external_followups / pending_external_followups_generation are the workflow-owned
# durable queue; a caller could otherwise inject actor identity into a restored follow-up.
# - timed_out_inactivity / timed_out_wall_clock / sandbox_gone are the workflow's terminal reason
# markers, written only by the update_task_run_status activity. Slack reads them to decide that
# a FAILED run was a timeout and stays quiet (post_slack_update._post_failure_or_timeout), so a
# caller could otherwise stamp one on a genuine failure and suppress its error card.
# These keys are reserved for server-owned run state, never PATCH input.
_PROTECTED_RUN_STATE_KEYS = frozenset(
{
"sandbox_environment_id",
# Worker-interpreted trial markers must never be caller-writable.
"scout_trial",
"scout_trial_judge",
"scout_trial_private",
"include_live_context",
"disable_skills",
"analytics_query_context",
"sandbox_oauth_token_ids",
# Sandbox run-start lineage and fan-out count. A child sandbox that removed its parent keys
# would count as a root run and start more generations, and a parent that reset its count
# would lift its fan-out cap.
"agent_parent_task_id",
"agent_parent_run_id",
"agent_started_run_count",
"resume_from_run_id",
"run_source",
"pr_base_branch",
"stack_base_branch",
"github_credential_source",
"token_cost",
"token_cost_incomplete",
"compute_cost",
"failure_error_type",
"startup_failure",
"startup_started_at",
"startup_completed_at",
"startup_provider",
"startup_runtime",
"agent_startup_attempt",
"agent_startup_success",
"unprocessed_request_ids",
TASK_OWNERSHIP_VERSION_STATE_KEY,
"pr_authorship_mode",
"repositories",
# Decides which repositories the run's GitHub token can write to.
"github_access_repositories",
"verified_pr_urls",
"prewarmed",
"await_user_message",
"warm_activation_started",
"warm_activated",
TASK_RUN_SUMMARY_STATE_KEY,
PRIOR_RUN_SUMMARY_STATE_KEY,
TASK_RUN_TAGS_STATE_KEY,
PRIOR_RUN_TAGS_STATE_KEY,
"sandbox_id",
# Sandbox connection state is written only by the provisioning activity. A PATCHable
# sandbox_backend/sandbox_url would let a task controller point the account-wide hogland
# bearer (or the connect token) at an arbitrary server, so it stays server-owned.
"sandbox_backend",
"sandbox_url",
"sandbox_connect_token",
"sandbox_jwt_kid",
DEV_STACK_PREVIEW_STATE_KEY,
"sandbox_cpu_cores",
"sandbox_memory_gb",
"sandbox_ttl_seconds",
"inactivity_timeout_seconds",
"systemPrompt",
# Resolved from the project and personal settings; a PATCHable value would let a task
# controller write arbitrary text into the agent's user-level instructions file.
"agent_instructions",
"wizard_config",
"reconciled_pr_merge_url",
"wizard_head_branch",
"use_modal_vm_sandbox",
# The image a run boots from; a PATCHed value would pick an image the task never asked for.
"sandbox_template",
# Rollout stamps written once at dispatch by _capture_run_feature_flags or at run
# creation; a PATCHable value would let a task controller bypass the org feature flags
# (for telemetry, that means injecting the internal OTLP capture token into their
# sandbox and re-enabling the run-log mirror with the rollout off).
AGENT_OTEL_TELEMETRY_STATE_KEY,
"sandbox_event_ingest_enabled",
"overlap_clone_boot_enabled",
"stream_presence_gated",
"stream_thin_tail",
PR_LOOP_ENABLED_STATE_KEY,
"snapshot_external_id",
"snapshot_kind",
"snapshot_mount_path",
*SERVER_OWNED_RESUME_STATE_KEYS,
"workflow_id",
"pending_dispatch",
"cancel_requested_at",
"cancel_requested_by_user_id",
"cancel_source",
"cancel_fallback_cleanup_complete",
"cancel_fallback_stream_generation",
"stream_generation",
"pending_external_followups",
"pending_external_followups_generation",
"pending_external_followups_checkpoint",
"task_management_ci_idle_skips",
"task_management_ci_wait_checks",
# Terminal reason markers owned by the workflow (see the note above). Spelled as literals
# rather than imported from the update_task_run_status activity, which would pull temporalio
# onto this module's import path; the workflow writes them through
# TaskRun.update_state_atomic, which does not go through this filter.
"timed_out_inactivity",
"timed_out_wall_clock",
"sandbox_gone",
TASK_ANALYSIS_ACTIVITIES_STATE_KEY,
ANALYSIS_TARGET_TASK_ID_STATE_KEY,
ANALYSIS_TARGET_RUN_ID_STATE_KEY,
# Server-stamped at analysis creation (task_analysis._target_context_state) and read back
# at activity-report time to attribute the captured event to a repository and sandbox
# image. A PATCHable value would let the sandbox agent forge that attribution.
ANALYSIS_TARGET_REPOSITORY_STATE_KEY,
ANALYSIS_TARGET_IMAGE_ID_STATE_KEY,
ANALYSIS_TARGET_IMAGE_NAME_STATE_KEY,
# Credential grant decided at Task.create_and_run time by server-owned callers (the scout
# runner); a PATCHable key would let any task controller mint a GitHub token onto a
# queued repo-less run.
"github_read_access",
"github_token_scope",
# Historical loop runs use this server stamp to keep owner credential revocation fail-closed.
"loop_id",
# Stamped at creation by workflow tasks: a PATCHable value would widen the run's connector allowlist.
"config_snapshot",
# Stamped once at run creation. The review carve-outs read ai_stage="implementation" as proof
# a run is self-driving, so a PATCHable value would forge that and unlock the bot/draft bypass.
# is_interactive_signals_run reads it the same way, so forging it would move the run off
# the interactive budget and out of its per-run spend ceiling.
"ai_stage",
"billing_product",
# A removed stamp lets a model change leave the token's pin, and the gateway denies every turn.
GATEWAY_PRODUCT_STATE_KEY,
# Names the agent (scout, custom agent, workflow) the run executes, lifted onto its
# $ai_generation events. A PATCHable value would bill a caller's spend to another agent.
"ai_agent_name",
# The server-generated head branch the run->PR link is keyed on (find_signal_implementation_run).
# A PATCHable value would let a caller re-aim the approve-first carve-out at any App-authored
# PR, which is the exact forgery the stamp exists to prevent.
"self_driving_head_branch",
# The run's model posture, chosen at creation by the server-owned caller and read back out
# of state when the run dispatches. It decides what the run costs, and for a run routed to
# an unbilled gateway product (create_wizard_cloud_run pins claude-sonnet-5 for the
# `onboarding` product) it is the only thing keeping the run off the more expensive models
# that product still allowlists. Every writer is server-side, so nothing legitimate PATCHes
# these.
"runtime_adapter",
"provider",
"model",
"reasoning_effort",
# The OpenAI queue the run's Codex turns join; `priority` costs more than standard.
"service_tier",
"claude_model_access",
"claude_subscription_user_id",
"codex_model_access",
"codex_subscription_user_id",
"rtk_effective",
"benjamin_effective",
"usage_metrics_recorded",
# get_task_run_actor_user mints the sandbox OAuth token for slack_actor_user_id when
# interaction_origin is "slack"; a removed actor falls back to the task creator.
"interaction_origin",
"slack_actor_user_id",
"slack_actor_slack_user_id",
# Names the autoresearch training run this TaskRun finalizes when it ends (training.ingestion).
"autoresearch_training_run_id",
# Set only when the agent's `finish` call saves its report. A forged marker would stop the
# relay from saving the run's final message and make readers trust a caller-written one.
TASK_RUN_FINISH_REPORT_STATE_KEY,
}
)
_TERMINAL_TASK_RUN_STATUSES = (TaskRun.Status.COMPLETED, TaskRun.Status.FAILED, TaskRun.Status.CANCELLED)
TASK_RUN_FAILURE_ERROR_TYPES = (
"agent_reported",
"agent_server_crash",
"agent_declined",
"output_parse_failed",
"poll_timeout",
"pi_runtime_error",
"upstream_stream_terminated",
"upstream_connection_error",
"upstream_timeout",
"upstream_provider_failure",
"upstream_request_rejected",
"content_block_rejection",
"turn_ended_without_response",
"subscription_usage_limit",
"task_spend_limit",
"agent_error",
"ActiveSessionCapError",
)
# `output.pr_merged` is GitHub's word, recorded by the PR webhook (`_record_run_pr_merged`) — never
# the caller's. Signals reads it to decide refund finality (billing.report_pr_is_merged): a report
# whose PR merged keeps its resolved status through a refund instead of being suppressed and having
# its PR closed. Any caller-writable path to this flag would let a `task:write` holder mark an open
# PR merged, resolve the report, and refund it while keeping the work — so every output writer has to
# go through `_merge_caller_output`, not merge caller output directly.
_WEBHOOK_ATTESTED_RUN_OUTPUT_KEYS = frozenset({"pr_merged"})
def _carries_final_message(validated_data: dict) -> bool:
output = validated_data.get("output")
return isinstance(output, dict) and isinstance(output.get("final_message"), str) and bool(output["final_message"])
def is_finish_report_output(output: object) -> bool:
if not isinstance(output, dict) or set(output) != {"final_message"}:
return False
report = output["final_message"]
return isinstance(report, str) and 0 < len(report) <= FINAL_MESSAGE_MAX_CHARS
def _apply_caller_output(stored: object, incoming: dict, merged: dict) -> dict:
"""Enforce the webhook-attested keys on a caller's output write.
`merged` is whatever the writer built from `incoming` (a wholesale replacement for
`set_task_run_output`, a merge over stored output for the PATCH path); this drops any attested
key the caller supplied and restores the stored one. The attestation is bound to the PR it was
made about, so when the caller points the run at a different `pr_url` the stored flag described
the old PR and is dropped rather than silently transferred onto the new one.
"""
existing = stored if isinstance(stored, dict) else {}
same_pr = not incoming.get("pr_url") or incoming["pr_url"] == existing.get("pr_url")
for key in _WEBHOOK_ATTESTED_RUN_OUTPUT_KEYS:
merged.pop(key, None)
if same_pr and existing.get(key):
merged[key] = existing[key]
return merged
def _task_run_queryset():
return TaskRun.objects.select_related(
"task", "task__created_by", "task__github_integration", "task__github_user_integration"
)
def _get_task_for_run_control(task_id: str | UUID, team_id: int, user_id: int | None) -> Task | None:
"""The task, only if the user may drive runs on it (``task_control_q``, not mere visibility)."""
return Task.objects.filter(id=task_id, team_id=team_id).filter(task_control_q(user_id)).first()
def _get_visible_run(run_id: str | UUID, task_id: str | UUID, team_id: int) -> TaskRun | None:
"""A run scoped to its parent task + team. Caller is responsible for task visibility."""
return _task_run_queryset().filter(pk=run_id, team_id=team_id, task_id=task_id).first()
def task_run_exists(run_id: str | UUID, task_id: str | UUID, team_id: int) -> bool:
"""Precheck so callers can 404 before doing expensive work (e.g. a render)."""
try:
return TaskRun.objects.filter(pk=run_id, team_id=team_id, task_id=task_id).exists()
except (ValueError, TypeError, DjangoValidationError):
return False
def task_run_matches_current_ownership(run_id: str | UUID, task_id: str | UUID, team_id: int) -> bool:
try:
run = _task_run_queryset().filter(pk=run_id, team_id=team_id, task_id=task_id).first()
except (ValueError, TypeError, DjangoValidationError):
return False
return run is not None and run.matches_task_ownership()
def _shared_slack_thread_q() -> Q:
"""Slack tasks whose thread is not a direct message.
Phrased as "not private" rather than "is a channel" so a mapping we never classified — a
row predating the column, or a lookup Slack refused — keeps the team-wide read access it
has today instead of silently narrowing to the thread starter.
The ``origin_product`` test leads so the subquery is only reached for Slack tasks; every
other task short-circuits on an indexed column before touching the mapping table.
"""
from products.slack_app.backend.models import ( # noqa: PLC0415 — cross-product import kept off the api import path
PRIVATE_CONVERSATION_TYPES,
SlackThreadTaskMapping,
)
private_thread = SlackThreadTaskMapping.objects.filter(
task_id=OuterRef("pk"),
conversation_type__in=sorted(PRIVATE_CONVERSATION_TYPES),
)
return Q(origin_product=Task.OriginProduct.SLACK) & Q(~Exists(private_thread))
def task_accessible_for_run_view(
task_id: str | UUID,
team_id: int,
user_id: int | None,
*,
bypass_visibility: bool = False,
for_control: bool = False,
sandbox_task_id: UUID | None = None,
sandbox_request: bool = False,
) -> bool:
"""Whether the parent task exists and (unless bypassed) is visible to the user.
Mirrors the parent-task gate in ``TaskRunViewSet.safely_get_queryset``: runs are always scoped
to a task, and access to that task is gated by ``task_visibility_q`` except for internal-debug
read actions, which the caller signals via ``bypass_visibility``. Run-mutating actions pass
``for_control`` to use the narrower ``task_control_q`` — public-channel visibility lets
teammates watch a run, not drive it.
Task-bound sandbox callers set ``bypass_visibility`` only after the view verifies that
the OAuth token's ``sandbox_task_id`` matches this task.
Tasks from a shared Slack conversation are readable by the whole team. Such a thread is
multiplayer: every member of the conversation already sees the agent's replies and follows
the links in them, so gating those links on the one person who opened the thread makes the
reply unusable for everyone else. The task itself is filed in its creator's personal space,
so ``task_visibility_q`` alone would hide it. Read-only on purpose — driving the run stays
with the creator, whose credentials the sandbox runs under.
Threads from a direct message are excluded: a DM has no audience beyond its author, so
there is nobody the widened read is for. See ``PRIVATE_CONVERSATION_TYPES``.
"""
trial_visibility = scout_trial_visibility_q(user_id)
if sandbox_request or sandbox_task_id is not None:
trial_visibility = ~Task.scout_experiment_q() | Q(id=sandbox_task_id)
visibility = trial_visibility & Q(deleted=False)
if not bypass_visibility:
scope_q = task_control_q(user_id) if for_control else task_visibility_q(user_id) | _shared_slack_thread_q()
visibility &= scope_q
# Classify the same row used for authorization, including denied reads whose errors stay private.
task = (
Task.objects.filter(id=task_id, team_id=team_id)
.annotate(
is_trial=Case(When(Task.scout_experiment_q(), then=Value(True)), default=Value(False)),
accessible=Exists(Task.objects.filter(id=OuterRef("pk"), team_id=team_id).filter(visibility)),
)
.values("is_trial", "accessible", "profile", "created_by_id")
.first()
)
if task is not None and task["is_trial"]:
tag_queries(is_scout_experiment=True)
if task is None or not task["accessible"]:
return False
acts_on_its_own_task = sandbox_task_id is not None and str(sandbox_task_id) == str(task_id)
if for_control and not (bypass_visibility or acts_on_its_own_task):
return drive_allowed(task["profile"], created_by_id=task["created_by_id"], user_id=user_id)
return True
def list_task_run_ids(task_id: str | UUID, team_id: int) -> list[UUID]:
"""Ids of every run of a task, team-scoped. Caller enforces task visibility."""
return list(TaskRun.objects.filter(team_id=team_id, task_id=task_id).values_list("id", flat=True))
def list_task_runs(
task_id: str | UUID,
team_id: int,
*,
user_id: int | None = None,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> list[contracts.TaskRunDetailDTO]:
"""All runs for a task, team-scoped. Caller enforces task visibility."""
runs = _task_run_queryset().filter(team_id=team_id, task_id=task_id)
return [
_task_run_detail_to_dto(run, user_id=user_id, analytics_context_reader=analytics_context_reader) for run in runs
]
def get_task_run_source(run_id: str | UUID, task_id: str | UUID, team_id: int) -> str | None:
return (
TaskRun.objects.filter(pk=run_id, team_id=team_id, task_id=task_id)
.values_list("state__run_source", flat=True)
.first()
)
def get_task_run_claude_model_access(run_id: str | UUID, task_id: str | UUID, team_id: int) -> str | None:
return (
TaskRun.objects.filter(pk=run_id, team_id=team_id, task_id=task_id)
.values_list("state__claude_model_access", flat=True)
.first()
)
def get_task_run_detail(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
include_agent_state: bool = False,
user_id: int | None = None,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> contracts.TaskRunDetailDTO | None:
"""A single run as a detail DTO, scoped to its task + team.
``include_agent_state`` is for the run's own task-bound sandbox only: it adds the
boot-prompt keys that are withheld from human readers.
"""
run = _get_visible_run(run_id, task_id, team_id)
return (
_task_run_detail_to_dto(
run,
include_agent_state=include_agent_state,
user_id=user_id,
analytics_context_reader=analytics_context_reader,
)
if run is not None
else None
)
def get_task_run_stream_info(
run_id: str | UUID, task_id: str | UUID, team_id: int
) -> contracts.TaskRunStreamInfoDTO | None:
"""The minimal run facts the SSE stream view needs. ``None`` if the run isn't found."""
from products.tasks.backend.metrics import ( # noqa: PLC0415 — keep prometheus deps off the api import path
origin_product_label,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return contracts.TaskRunStreamInfoDTO(
id=run.id,
state=run.state or {},
origin_product=origin_product_label(run),
is_terminal=run.is_terminal,
state_event=run.build_stream_state_event(),
)
def signal_workflow_completion(
run_id: str | UUID, status: str, error_message: str | None, error_type: str | None = None
) -> None:
"""Send a completion signal to a run's Temporal workflow (best-effort)."""
import asyncio # noqa: PLC0415 — only needed when signalling
from posthog.temporal.common.client import sync_connect # noqa: PLC0415 — keep temporalio off the api import path
from products.tasks.backend.temporal.process_task.workflow import ( # noqa: PLC0415 — keep temporalio off the api import path
ProcessTaskWorkflow,
)
run = TaskRun.objects.filter(pk=run_id).first()
if run is None or (run.scheduled_at is not None and run.queued_at is None):
return
if error_type is not None:
record_run_failure_cause(run.id, error_type)
try:
client = sync_connect()
handle = client.get_workflow_handle(run.workflow_id)
asyncio.run(handle.signal(ProcessTaskWorkflow.complete_task, args=[status, error_message]))
logger.info("Signaled workflow completion for task run %s with status %s", run.id, status)
except Exception as e:
logger.warning("Failed to signal workflow completion for task run %s: %s", run.id, e)
def _post_slack_update_for_pr(run: TaskRun) -> None:
pr_url = (run.output or {}).get("pr_url") if isinstance(run.output, dict) else None
if not pr_url:
return
from products.slack_app.backend.models import ( # noqa: PLC0415 — cross-product import kept off the api import path
SlackThreadTaskMapping,
)
from products.tasks.backend.temporal.process_task.activities.post_slack_update import ( # noqa: PLC0415 — keep temporalio off the api import path
PostSlackUpdateInput,
post_slack_update,
)
try:
mapping = (
SlackThreadTaskMapping.objects.filter(task_run=run)
.order_by("-updated_at")
.values("integration_id", "channel", "thread_ts", "mentioning_slack_user_id")
.first()
)
if not mapping:
return
post_slack_update(
PostSlackUpdateInput(
run_id=str(run.id),
slack_thread_context={
"integration_id": mapping["integration_id"],
"channel": mapping["channel"],
"thread_ts": mapping["thread_ts"],
"mentioning_slack_user_id": mapping["mentioning_slack_user_id"],
},
)
)
except Exception:
logger.exception("task_run_slack_update_for_pr_failed for run %s", run.id)
def _is_github_pull_request_url_for_repository(pr_url: str, repository: str | None) -> bool:
if not repository:
return False
try:
parsed_url = urlparse(pr_url)
except ValueError:
return False
if parsed_url.scheme != "https" or parsed_url.netloc != "github.com":
return False
if parsed_url.params or parsed_url.query or parsed_url.fragment:
return False
path_parts = parsed_url.path.strip("/").split("/")
repository_parts = repository.strip("/").split("/")
if len(path_parts) != 4 or len(repository_parts) != 2:
return False
return (
path_parts[0].lower() == repository_parts[0].lower()
and path_parts[1].lower() == repository_parts[1].lower()
and path_parts[2] == "pull"
and path_parts[3].isdigit()
)
def _send_wizard_pr_ready_email_for_pr(run: TaskRun) -> None:
pr_url = (run.output or {}).get("pr_url") if isinstance(run.output, dict) else None
if not pr_url or run.task.origin_product != Task.OriginProduct.ONBOARDING:
return
if run.task.created_by_id is None:
return
if not _is_github_pull_request_url_for_repository(pr_url, run.task.repository):
logger.warning(
"wizard_pr_ready_email_invalid_pr_url",
extra={"run_id": str(run.id), "task_id": str(run.task_id), "repository": run.task.repository},
)
return
if not run.task.mark_pr_ready_email_queued(pr_url):
return
from posthog.tasks.email import send_wizard_pr_ready_email # noqa: PLC0415 - keep email task import lazy
transaction.on_commit(lambda: send_wizard_pr_ready_email.delay(str(run.id)))
def _refresh_self_driving_quota_for_pr(run: TaskRun, old_pr_url: str | None) -> None:
"""Queue an org-level self-driving quota re-evaluation when a self-driving-origin run records its first
PR URL. That write is the report's billable moment (products/signals/backend/billing.py), so
re-evaluating now lets the quota limiter flag the org within seconds of the PR that crosses
its limit (for runs created the same UTC day; `refresh_org_self_driving_quota` documents the
cross-midnight gap); the 15-minute quota cron only re-reads usage on its next tick. Dispatched
on commit so the task reads the committed pr_url; best-effort because the cron is the backstop.
Never raises: the callers signal workflow completion and run other PR side effects right after,
and a refresh hiccup must not abort those or turn an already-committed run write into a 500.
"""
try:
if old_pr_url or (run.state or {}).get("billing_product") == "posthog_ai":
return
new_pr_url = (run.output or {}).get("pr_url") if isinstance(run.output, dict) else None
if not new_pr_url or run.task.origin_product != Task.OriginProduct.SIGNAL_REPORT:
return
# Billing only ever counts GitHub PR URLs (billing.py validates the same prefix), so a
# recompute for any other output.pr_url string is a guaranteed no-op; don't let arbitrary
# client-written values enqueue org-wide refreshes. Literal kept local because tasks code
# must not import signals internals.
if not new_pr_url.startswith(GITHUB_PR_URL_PREFIX):
return
organization_id = Team.objects.filter(id=run.task.team_id).values_list("organization_id", flat=True).first()
if organization_id is None:
return
from ee.tasks.quota_limiting import (
refresh_org_self_driving_quota_task, # noqa: PLC0415 — keep billing deps off the api import path
)
def _dispatch() -> None:
try:
refresh_org_self_driving_quota_task.delay(str(organization_id))
except Exception:
logger.warning(
"self_driving_quota_refresh_dispatch_failed", extra={"run_id": str(run.id)}, exc_info=True
)
transaction.on_commit(_dispatch)
except Exception:
logger.warning("self_driving_quota_refresh_failed", extra={"run_id": str(run.id)}, exc_info=True)
def enforce_self_driving_free_trial(
team: Team, *, report_id: str | None = None, stage: str = "manual_create", enabled: bool | None = None
) -> None:
"""Keep PR-opening report work unavailable during the self-driving trial.
Resolve enabled before taking database locks, since flag evaluation can use the network.
"""
from products.signals.backend.facade.self_driving import ( # noqa: PLC0415 — cross-product read kept off the api import path
FreeTrialPullRequestRefused,
capture_signal_report_free_trial_paused,
self_driving_free_trial_enabled,
)
if not (self_driving_free_trial_enabled(team) if enabled is None else enabled):
return
capture_signal_report_free_trial_paused(team, report_id=report_id, stage=stage)
raise FreeTrialPullRequestRefused()
def enforce_self_driving_pr_quota(team: Team, *, report_id: str | None = None, stage: str = "manual_create") -> None:
from posthog.exceptions import QuotaLimitExceeded # noqa: PLC0415 — keep billing deps off the api import path
from products.signals.backend.facade.self_driving import ( # noqa: PLC0415 — cross-product read kept off the api import path
capture_signal_report_quota_paused,
self_driving_limit_name,
self_driving_quota_gate,
)
gate = self_driving_quota_gate(team)
if gate.limited:
capture_signal_report_quota_paused(team, report_id=report_id, stage=stage, enforced=gate.enforced)
if gate.enforced:
raise QuotaLimitExceeded(
f"Your organization reached its self-driving {self_driving_limit_name(team)}. "
"New work is paused; work already underway will finish. "
"Increase the limit in Settings > Billing, or ask an organization admin to do so."
)
def update_task_run(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
validated_data: dict,
only_if_non_terminal: bool = False,
only_if_not_started: bool = False,
caller_is_agent: bool = False,
user_id: int | None = None,
include_log_url: bool = True,
) -> contracts.TaskRunDetailDTO | None:
"""Apply a PATCH to a run: merge output/state, set completion, then dispatch side effects.
Mirrors ``TaskRunViewSet.partial_update`` byte-for-byte: protected state keys are stripped,
output/state merges take a row lock, terminal transitions signal Temporal + dispatch
push/Slack updates after commit, and a cloud→local transition cancels the workflow.
"""
from products.tasks.backend.logic.services.pr_reconciliation import ( # noqa: PLC0415 - avoids the facade/webhook import cycle
PullRequestReconciler,
)
from products.tasks.backend.metrics import ( # noqa: PLC0415 — keep prometheus deps off the api import path
observe_agent_turn_failed,
observe_prewarmed_unused_if_never_activated,
observe_task_run_terminal,
observe_wizard_run_unbound,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
validated_data = dict(validated_data)
if "state" in validated_data and not isinstance(validated_data["state"], dict):
raise ValueError("Run state must be an object.")
if (
"status" in validated_data
and not caller_is_agent
and run.task.origin_product == Task.OriginProduct.TASK_ANALYSIS
):
# A human-driven status write on an analysis run is a way to buy another funded analysis:
# marking it failed or cancelled frees the per-run idempotency slot. The workflow and the
# run's own agent write status through paths that do not pass through here.
validated_data.pop("status")
if (
"status" in validated_data
and not caller_is_agent
and run.task.origin_product == Task.OriginProduct.WORKFLOW
and validated_data["status"] != TaskRun.Status.CANCELLED
):
# A finished status wakes the workflow step with this run's output, so only the agent may set it.
validated_data.pop("status")
has_output_merge = "output" in validated_data and isinstance(validated_data["output"], dict)
has_state_merge = "state" in validated_data and isinstance(validated_data["state"], dict)
if has_state_merge:
validated_data["state"] = {
k: v for k, v in validated_data["state"].items() if k not in _PROTECTED_RUN_STATE_KEYS
}
state_remove_keys = [
k for k in (validated_data.get("state_remove_keys") or []) if k not in _PROTECTED_RUN_STATE_KEYS
]
raw_state_append = validated_data.get("state_append")
state_append = (
{k: v for k, v in raw_state_append.items() if k not in _PROTECTED_RUN_STATE_KEYS}
if isinstance(raw_state_append, dict)
else {}
)
has_state_mutation = has_state_merge or bool(state_remove_keys) or bool(state_append)
update_fields: set[str] = set()
with transaction.atomic():
if (
has_output_merge
or has_state_mutation
or only_if_non_terminal
or only_if_not_started
or "status" in validated_data
or "branch" in validated_data
):
run = TaskRun.objects.select_for_update().get(pk=run.pk)
if only_if_not_started and run.status != TaskRun.Status.NOT_STARTED:
return None
if only_if_non_terminal and run.is_terminal:
if validated_data.get("status") == run.status:
transaction.on_commit(lambda: resume_workflow_step_for_run(run))
return _task_run_detail_to_dto(run, user_id=user_id, include_log_url=include_log_url)
old_status = run.status
old_output = run.output
old_branch = run.branch
old_pr_url = (run.output or {}).get("pr_url") if isinstance(run.output, dict) else None
old_commit_head = _commit_push_head_sha(run.output)
for key, value in validated_data.items():
if key == "output" and isinstance(value, dict):
existing_output = run.output if isinstance(run.output, dict) else {}
# Same attested-key policy as set_task_run_output — this PATCH surface is
# caller-controlled too, so it can't be a back door to output.pr_merged.
merged_output = merge_pr_output(existing_output, value)
setattr(run, key, _apply_caller_output(existing_output, value, merged_output))
update_fields.add(key)
continue
if key in ("state_remove_keys", "state_append", "error_type"):
continue
if key == "state" and has_state_merge:
existing_state = run.state if isinstance(run.state, dict) else {}
next_state = dict(existing_state)
for remove_key in state_remove_keys:
next_state.pop(remove_key, None)
next_state.update(value)
setattr(run, key, next_state)
update_fields.add(key)
continue
setattr(run, key, value)
update_fields.add(key)
if state_remove_keys and not has_state_merge:
existing_state = run.state if isinstance(run.state, dict) else {}
next_state = dict(existing_state)
for remove_key in state_remove_keys:
next_state.pop(remove_key, None)
run.state = next_state
update_fields.add("state")
if state_append:
next_state = dict(run.state) if isinstance(run.state, dict) else {}
for append_key, item in state_append.items():
current = next_state.get(append_key)
if isinstance(current, list):
next_state[append_key] = [*current, item]
elif current is None:
next_state[append_key] = [item]
else:
# Appending to a key that holds a scalar used to drop the scalar. Keeping it as
# the first element loses nothing, and this path has no way to return a 400.
next_state[append_key] = [current, item]
run.state = next_state
update_fields.add("state")
new_status = validated_data.get("status")
if only_if_not_started and new_status == TaskRun.Status.CANCELLED:
# A dormant run has no workflow to complete its stream after cancellation.
run.state = {**(run.state or {}), "cancel_fallback_cleanup_complete": True}
update_fields.add("state")
if (
caller_is_agent
and new_status in {TaskRun.Status.COMPLETED, TaskRun.Status.FAILED}
and old_status != new_status
and _carries_final_message(validated_data)
):
output = run.output if isinstance(run.output, dict) else {}
run.output = {**output, "final_message": output["final_message"][:FINAL_MESSAGE_MAX_CHARS]}
run.state = {**(run.state or {}), TASK_RUN_FINISH_REPORT_STATE_KEY: True}
update_fields.update({"output", "state"})
elif (
caller_is_agent
and new_status == TaskRun.Status.COMPLETED
and old_status != new_status
and run.task.origin_product == Task.OriginProduct.WORKFLOW
and (run.state or {}).get("end_run_when_done")
):
if isinstance(run.output, dict):
run.output = {key: value for key, value in run.output.items() if key != "final_message"}
update_fields.add("output")
if new_status in _TERMINAL_TASK_RUN_STATUSES:
if not run.completed_at:
run.completed_at = django_timezone.now()
update_fields.add("completed_at")
update_fields.add("updated_at")
run.save(update_fields=list(update_fields))
PullRequestReconciler.schedule(run, previous_output=old_output, previous_branch=old_branch)
run.publish_stream_state_event()
if new_status in _TERMINAL_TASK_RUN_STATUSES and old_status != new_status:
# This PATCH performed the transition, so the status-update activity skips its count.
observe_task_run_terminal(
run,
error_type=validated_data.get("error_type")
or ("agent_reported" if new_status == TaskRun.Status.FAILED else None),
termination_reason=None,
)
try:
if run.environment == TaskRun.Environment.CLOUD:
refresh_task_run_cost(run_id=run.id, team_id=run.team_id)
run.refresh_from_db(fields=["state", "updated_at"])
except Exception:
logger.warning("task_run_cost_refresh_failed", extra={"run_id": str(run.id)}, exc_info=True)
if new_status in _TERMINAL_TASK_RUN_STATUSES and old_status != new_status:
if new_status == TaskRun.Status.FAILED:
observe_agent_turn_failed(run)
# This PATCH performed the DB transition, so it owns the task_run_failed
# capture. The workflow's status-update activity sees the row already
# FAILED and skips its own capture, keeping the event single-emitted.
run.capture_event(
"task_run_failed",
{
"error_message": truncate_error_message(run.error_message),
"error_type": validated_data.get("error_type") or "agent_reported",
"duration_seconds": run._duration_seconds(),
**run.failure_sandbox_backend_properties(),
},
)
observe_wizard_run_unbound(run)
# This write terminalizes the Run on its own — the cancel fallback takes it when the workflow
# is already gone — so the warm miss is booked here rather than by the status activity, which
# sees the row already terminal and skips.
observe_prewarmed_unused_if_never_activated(
run, reason="released" if new_status == TaskRun.Status.CANCELLED else "other"
)
signal_workflow_completion(
run.id, new_status, validated_data.get("error_message"), validated_data.get("error_type")
)
if new_status == TaskRun.Status.CANCELLED:
from products.tasks.backend.push_dispatcher import ( # noqa: PLC0415 — keep push deps off the api import path
notify_task_run_cancelled,
)
notify_task_run_cancelled(run)
new_pr_url = (run.output or {}).get("pr_url") if isinstance(run.output, dict) else None
if new_pr_url and new_pr_url != old_pr_url:
_refresh_self_driving_quota_for_pr(run, old_pr_url)
_post_slack_update_for_pr(run)
_send_wizard_pr_ready_email_for_pr(run)
post_pr_created_thread_update(run, new_pr_url)
# Surface the PR in the run's progress timeline the moment the agent reports it, so the install
# UI advances past "Started agent" instead of waiting on the 15-min CI follow-up loop to emit
# these. Tolerant: a logging/stream hiccup must not fail the PATCH.
try:
run.emit_progress_event("pr", "completed", "Opened pull request", "setup", detail=new_pr_url)
if (run.state or {}).get(PR_LOOP_ENABLED_STATE_KEY):
run.emit_progress_event("ci", "in_progress", "Keeping CI green", "setup")
except Exception:
logger.warning("task_run.pr_progress_emit_failed", extra={"run_id": str(run.id)}, exc_info=True)
if new_status in _TERMINAL_TASK_RUN_STATUSES and old_status != new_status:
run.close_ci_progress_step()
new_commit_head = _commit_push_head_sha(run.output)
if caller_is_agent and isinstance(run.output, dict) and new_commit_head and new_commit_head != old_commit_head:
post_commits_pushed_thread_update(run, run.output["commit_push"])
if new_status in _TERMINAL_TASK_RUN_STATUSES:
resume_workflow_step_for_run(run)
return _task_run_detail_to_dto(run, user_id=user_id, include_log_url=include_log_url)
TASK_RUN_SUMMARY_MAX_CHARS = 1500
TASK_RUN_TAGS_MAX_COUNT = 10
TASK_RUN_TAG_MAX_CHARS = 50
def validate_set_output(run_id: str | UUID, task_id: str | UUID, team_id: int, *, output: dict) -> str | None:
"""Validate output against the task's json_schema. Returns an error message or ``None``."""
import jsonschema # noqa: PLC0415 — only needed when a json_schema is set
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
task = run.task
if task.json_schema:
try:
jsonschema.validate(instance=output, schema=task.json_schema)
except jsonschema.ValidationError as e:
return f"Output validation error: {e.message}"
return None
def set_task_run_output(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, output: dict, user_id: int | None = None
) -> contracts.TaskRunDetailDTO | None:
"""Persist a run's output. Completes the run for structured-output tasks; posts Slack PR update."""
from products.tasks.backend.logic.services.pr_reconciliation import ( # noqa: PLC0415 - avoids the facade/webhook import cycle
PullRequestReconciler,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
task = run.task
# Preserve PR facts a webhook may have written concurrently: this assignment is wholesale,
# so a bare `= output` would drop output.pr_url recorded out of band.
with transaction.atomic():
run = TaskRun.objects.select_for_update().get(pk=run.pk, team_id=team_id)
existing = run.output if isinstance(run.output, dict) else {}
merged = merge_pr_output(existing, output)
run.output = _apply_caller_output(existing, output, merged)
run.save(update_fields=["output", "updated_at"])
PullRequestReconciler.schedule(run, previous_output=existing, previous_branch=run.branch)
_refresh_self_driving_quota_for_pr(run, existing.get("pr_url"))
if task.json_schema and not (run.state or {}).get("caller_ends_run"):
signal_workflow_completion(run.id, TaskRun.Status.COMPLETED, None)
run.publish_stream_state_event()
_post_slack_update_for_pr(run)
_send_wizard_pr_ready_email_for_pr(run)
if merged.get("pr_url"):
post_pr_created_thread_update(run, merged["pr_url"])
return _task_run_detail_to_dto(run, user_id=user_id)
def set_task_run_summary(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
summary: str,
tags: list[str] | None = None,
sync_task_tags: bool = True,
include_agent_state: bool = False,
user_id: int | None = None,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> contracts.TaskRunDetailDTO | None:
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
updates: dict[str, Any] = {TASK_RUN_SUMMARY_STATE_KEY: summary}
# Omitted tags keep the current set, so a summary-only call does not erase them.
if tags is not None:
updates[TASK_RUN_TAGS_STATE_KEY] = list(dict.fromkeys(tags))
with transaction.atomic():
run.state = TaskRun.update_state_atomic(run.id, updates=updates)
if sync_task_tags and tags is not None and not run.task.is_scout_experiment:
replace_tags_on_object(tags, run.task)
run.refresh_from_db()
run.publish_stream_state_event()
return _task_run_detail_to_dto(
run,
include_agent_state=include_agent_state,
user_id=user_id,
analytics_context_reader=analytics_context_reader,
)
def _entries_show_agent_activity(entries: list[dict]) -> bool:
"""Classify a log batch as agent activity, but only judge batches that speak ACP.
Within an ACP batch, only ``session/*`` notifications count as the agent doing work.
Infra frames (``_posthog/console``, credential-refresh notices, errors) must not reset
the workflow's inactivity timeout: the workflow's own periodic credential refresh makes
the sandbox log a line, so counting every frame lets a run whose agent went silent keep
itself alive forever.
Batches with no ACP frame at all are not sandbox chatter, they come from callers that
only ever post generic ``{type, message}`` entries. Those runs have always relied on the
append itself as their heartbeat, so they keep the old behaviour rather than silently
losing their inactivity extension.
"""
saw_acp_frame = False
for entry in entries:
notification = entry.get("notification")
if not isinstance(notification, dict):
continue
saw_acp_frame = True
method = notification.get("method")
if isinstance(method, str) and method.startswith("session/"):
return True
return bool(entries) and not saw_acp_frame
def append_task_run_log(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, entries: list[dict]
) -> contracts.TaskRunDetailDTO | None:
"""Append log entries to a run's S3 log and heartbeat its workflow.
The heartbeat only reports the agent as active when the entries show real agent
activity; sandbox infra frames are still appended but heartbeat with
``agent_active=False``, which the workflow's signal handler ignores.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
run.append_log(entries, lock_attempts=1)
run.clear_echoed_followup_messages(entries)
run.heartbeat_workflow(agent_active=_entries_show_agent_activity(entries))
return _task_run_detail_to_dto(run)
def attach_task_run_input_files(*, team_id: int, run_id: UUID, files: Sequence[contracts.TaskRunInputFile]) -> None:
"""Bind trusted, already-stored inputs inside the caller's run-creation transaction.
The caller owns the objects and verifies their scope before attaching them. Keeping their
immutable locations avoids storage I/O while the task creation transaction is open.
"""
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the facade import path
build_task_artifact_entry,
)
run = TaskRun.objects.get(id=run_id, team_id=team_id, task__team_id=team_id)
if run.status not in {TaskRun.Status.NOT_STARTED, TaskRun.Status.QUEUED} or run.artifacts:
raise ValueError("Input files must be attached before the task run starts.")
if len({file.id for file in files}) != len(files):
raise ValueError("Input files must have distinct identifiers.")
run.artifacts = [
build_task_artifact_entry(
artifact_id=file.id,
name=file.name,
artifact_type="file",
source="internal",
size=file.size_bytes,
content_type=file.content_type,
storage_path=file.storage_path,
)
for file in files
]
run.save(update_fields=["artifacts", "updated_at"])
def get_task_id_by_idempotency_key(team_id: int, key: str) -> UUID | None:
return Task.objects.filter(idempotency_key_q(key), team_id=team_id).values_list("id", flat=True).first()
def get_task_by_origin_key(
team_id: int, origin_key: str, *, include_latest_run: bool = True
) -> contracts.TaskDetailDTO | None:
"""The live task carrying ``origin_key`` in ``team_id``, or None. Bypasses visibility: an
origin key is an idempotency handle for a system writer, not a user-facing lookup."""
task = Task.objects.filter(idempotency_key_q(origin_key), team_id=team_id, deleted=False).first()
return _task_detail_to_dto(task, include_latest_run=include_latest_run) if task is not None else None
def get_imported_task_run(task_id: str | UUID, team_id: int) -> contracts.TaskRunDetailDTO | None:
"""The run that holds a task's imported transcript (``state.imported_from`` set), or None."""
run = (
TaskRun.objects.filter(task_id=task_id, team_id=team_id, state__has_key="imported_from")
.order_by("created_at", "id")
.first()
)
return _task_run_detail_to_dto(run) if run is not None else None
def create_imported_task(
team_id: int,
user_id: int,
*,
title: str,
origin_key: str,
internal: bool,
created_at: datetime,
) -> contracts.TaskDetailDTO:
"""Create the task that hosts a transcript imported from elsewhere.
Backdated to the source's creation time so the task list keeps the order the user remembers.
The title comes from the source, not the user, so a later rename of the task must win over it.
"""
return create_task(
team_id,
user_id,
validated_data={
"title": title,
"title_manually_set": False,
"description": "",
"origin_product": Task.OriginProduct.POSTHOG_AI,
"origin_key": origin_key,
"internal": internal,
"created_at": created_at,
},
)
def create_imported_task_run(
task_id: str | UUID,
team_id: int,
*,
state: dict,
created_at: datetime,
completed_at: datetime,
) -> contracts.TaskRunDetailDTO:
"""Create a completed run that never executed, to host a transcript imported from elsewhere.
The run is backdated to the source's timestamps so the task sorts and reads as old as the
conversation it came from. Nothing dispatches a workflow for it; a later real run chains to it
through ``resume_from_run_id`` like any earlier run. A task holds one import run: the create
runs under the task's row lock and returns the existing run when a concurrent import won.
"""
with transaction.atomic():
task = Task.objects.select_for_update().get(id=task_id, team_id=team_id)
existing = (
TaskRun.objects.filter(task=task, team_id=team_id, state__has_key="imported_from")
.order_by("created_at", "id")
.first()
)
if existing is not None:
return _task_run_detail_to_dto(existing)
run = TaskRun.objects.create(
task=task,
team_id=team_id,
status=TaskRun.Status.COMPLETED,
environment=TaskRun.Environment.CLOUD,
state=state,
completed_at=completed_at,
)
# created_at is auto_now_add, so the backdate has to go through update().
TaskRun.objects.filter(id=run.id).update(created_at=created_at)
run.refresh_from_db()
return _task_run_detail_to_dto(run)
def append_imported_task_run_log(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
entries: list[dict],
batch_id: str,
expected_state: dict,
state_updates: dict,
completed_at: datetime,
) -> bool:
"""Append lines to an import run's log and record how far the source has been copied.
Holds the run's row lock across the append so two copies of the same source cannot both
append the same lines: the append only happens while ``expected_state`` still matches the
run's state, and returns False when another writer moved it on first. ``batch_id`` names
this batch in the log, so a retry after the append succeeded but the state write failed
skips the append instead of writing the lines twice. Imported transcripts are user chat
history, so the log is never tagged for expiry, and there is no workflow to heartbeat.
``completed_at`` follows the source so the run reads as current as the conversation it copies.
"""
with transaction.atomic():
run = TaskRun.objects.select_for_update().get(id=run_id, task_id=task_id, team_id=team_id)
state = run.state or {}
if any(state.get(key) != value for key, value in expected_state.items()):
return False
run.append_log(entries, ttl_days=None, batch_id=batch_id)
run.state = {**state, **state_updates}
run.completed_at = completed_at
run.save(update_fields=["state", "completed_at"])
return True
def touch_imported_task(task_id: str | UUID, team_id: int, *, title: str | None, last_activity_at: datetime) -> None:
"""Keep an imported task's list row in step with its source conversation."""
tasks = Task.objects.filter(id=task_id, team_id=team_id)
tasks.update(last_activity_at=last_activity_at)
if title:
# A title the user set on the task outranks the source's generated one.
tasks.filter(title_manually_set=False).update(title=title)
def clear_task_run_conversation(
run_id: str | UUID, task_id: str | UUID, team_id: int
) -> tuple[Literal["cleared", "not_found", "not_terminal"], contracts.TaskRunDetailDTO | None]:
"""Write a `/clear` boundary into a finished run's log, for the next run to resume from.
Only for a finished run: a live one has a sandbox that owns the clear (and a writer
streaming into the same log object, which this read-modify-write append would race),
so the caller sends `/clear` to it as an ordinary message instead.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return "not_found", None
with transaction.atomic():
# Hold the row lock across the append: resume_task_run_in_cloud locks this same
# row to flip a finished run back to QUEUED, so locking here keeps the terminal
# check true while the boundary is written, and serializes concurrent clears so
# the dedup in emit_conversation_cleared holds. The block writes nothing to
# Postgres; the lock is mutual exclusion only.
run = _task_run_queryset().select_for_update(of=("self",)).get(pk=run.pk)
if not run.is_terminal:
return "not_terminal", None
run.emit_conversation_cleared()
return "cleared", _task_run_detail_to_dto(run)
def ensure_task_run_session(run_id: str | UUID) -> UUID:
with transaction.atomic():
run = TaskRun.objects.select_for_update(of=("self",)).select_related("task__team").get(id=run_id)
if run.active_task_session_id is not None:
return run.active_task_session_id
task_session = TaskSession.create_for_task(run.task)
run.active_task_session = task_session
run.save(update_fields=["active_task_session", "updated_at"])
return task_session.id
def get_task_run_session(
run_id: str | UUID, task_id: str | UUID, team_id: int
) -> tuple[UUID, str | None, str | None] | None:
from posthog.storage import object_storage # noqa: PLC0415
run = _get_visible_run(run_id, task_id, team_id)
if run is None or run.active_task_session_id is None:
return None
task_session = TaskSession.objects.unscoped().get(id=run.active_task_session_id)
if task_session.object_storage_key is None:
return task_session.id, None, None
download_url = object_storage.get_presigned_url(task_session.object_storage_key, expiration=3600)
if not download_url:
raise RuntimeError("Unable to prepare task session download")
return task_session.id, download_url, task_session.content_sha256
def _validate_task_session_content(content: bytes) -> None:
if not content or len(content) > TASK_SESSION_MAX_SIZE_BYTES:
raise ValueError("The task session content size is invalid")
def _get_open_sandbox_session(run_id: UUID, sandbox_id: str) -> SandboxSession | None:
return (
SandboxSession.objects.unscoped()
.filter(
task_run_id=run_id,
sandbox_id=sandbox_id,
ended_at__isnull=True,
)
.first()
)
def _delete_task_session_object(task_session_id: UUID, object_storage_key: str) -> None:
from posthog.storage import object_storage # noqa: PLC0415
try:
object_storage.delete(object_storage_key)
except Exception as error:
logger.warning(
"task_session.failed_to_delete_object",
extra={
"task_session_id": str(task_session_id),
"object_storage_key": object_storage_key,
"error": str(error),
},
)
def get_run_plan(state: dict[str, Any] | None) -> contracts.RunPlan | None:
"""The plan a run bills to, or `None` for a run on PostHog credits."""
try:
access = resolve_model_access(state or {})
except InvalidModelAccess:
return None
if access.adapter is None:
return None
return contracts.RunPlan(plan_name=SUBSCRIPTION_PLAN_NAMES[access.adapter], owner_user_id=access.owner_id)
def ensure_subscription_owner(state: dict[str, Any] | None, actor_user_id: int | None) -> None:
"""Refuse anyone but the owner of the plan a run bills to. A run on PostHog credits allows everyone."""
run_state = state or {}
for adapter, plan_name in SUBSCRIPTION_PLAN_NAMES.items():
if (
run_state.get(f"{adapter}_model_access") == "own-subscription"
and run_state.get(f"{adapter}_subscription_user_id") != actor_user_id
):
raise PermissionDenied(f"Only the user who started this run can use its {plan_name}.")
def validate_task_run_sandbox_token(
token: str,
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
sandbox_id: str,
) -> bool:
from jwt import InvalidTokenError # noqa: PLC0415
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415
validate_sandbox_event_ingest_token,
)
try:
claims = validate_sandbox_event_ingest_token(token)
except (InvalidTokenError, ValueError):
return False
return (
claims.run_id == str(run_id)
and claims.task_id == str(task_id)
and claims.team_id == team_id
and claims.sandbox_id == sandbox_id
)
def issue_codex_subscription_access_grant(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
run_token: str,
rejected_access_token_sha256: str | None,
) -> CodexAccessGrant | None:
"""The run owner's ChatGPT access token for a Codex own-subscription run.
None when the run token does not authorize this run: wrong run, a sandbox that is no
longer the run's active sandbox, or a run that does not use the owner's ChatGPT plan.
Raises ``CodexReauthRequired`` when the owner must reconnect, ``CodexAuthError`` when
OpenAI could not refresh the token.
"""
from jwt import InvalidTokenError # noqa: PLC0415
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415
validate_codex_subscription_run_token,
)
from products.tasks.backend.temporal.metrics import increment_credential_refresh # noqa: PLC0415
try:
claims = validate_codex_subscription_run_token(run_token)
except (InvalidTokenError, ValueError):
return None
if claims.run_id != str(run_id) or claims.task_id != str(task_id) or claims.team_id != team_id:
return None
run = TaskRun.objects.filter(id=run_id, task_id=task_id, team_id=team_id).only("id", "state").first()
if run is None:
return None
state = run.state or {}
owner_id = state.get("codex_subscription_user_id")
if (
state.get("sandbox_id") != claims.sandbox_id
or state.get("codex_model_access") != "own-subscription"
or not isinstance(owner_id, int)
):
return None
try:
grant = CodexUserIntegration.issue_access_grant(
owner_id, rejected_access_token_sha256=rejected_access_token_sha256, source="tasks_run"
)
except CodexReauthRequired:
increment_credential_refresh("codex", "orphaned")
raise
except CodexAuthError:
increment_credential_refresh("codex", "failed")
raise
increment_credential_refresh("codex", "refreshed" if grant.refreshed else "skipped")
return grant
def sync_task_run_session(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
sandbox_id: str,
expected_content_sha256: str | None,
content: bytes,
) -> tuple[UUID, str] | None:
from posthog.storage import object_storage # noqa: PLC0415
visible_run = _get_visible_run(run_id, task_id, team_id)
if visible_run is None or visible_run.active_task_session_id is None:
return None
_validate_task_session_content(content)
if _get_open_sandbox_session(visible_run.id, sandbox_id) is None:
raise ValueError("The task session writer is not the active sandbox")
content_sha256 = hashlib.sha256(content).hexdigest()
object_storage_key = (
f"task-sessions/{visible_run.task.team.organization_id}/{visible_run.task_id}/"
f"{visible_run.active_task_session_id}/{uuid4()}.jsonl"
)
object_storage.write(object_storage_key, content)
previous_object_storage_key: str | None = None
try:
with transaction.atomic():
locked_run = TaskRun.objects.select_for_update(of=("self",)).get(id=visible_run.id)
if locked_run.active_task_session_id != visible_run.active_task_session_id:
raise ValueError("The task session sync is stale")
if _get_open_sandbox_session(locked_run.id, sandbox_id) is None:
raise ValueError("The task session writer is not the active sandbox")
task_session = TaskSession.objects.unscoped().select_for_update().get(id=locked_run.active_task_session_id)
if task_session.content_sha256 == content_sha256:
transaction.on_commit(lambda: _delete_task_session_object(task_session.id, object_storage_key))
return task_session.id, content_sha256
if task_session.content_sha256 != expected_content_sha256:
raise ValueError("The task session content is stale")
previous_object_storage_key = task_session.object_storage_key
task_session.object_storage_key = object_storage_key
task_session.content_sha256 = content_sha256
task_session.size = len(content)
task_session.save(update_fields=["object_storage_key", "content_sha256", "size", "updated_at"])
if previous_object_storage_key is not None:
transaction.on_commit(lambda: _delete_task_session_object(task_session.id, previous_object_storage_key))
task_session.tag_object()
return task_session.id, content_sha256
except Exception:
_delete_task_session_object(visible_run.active_task_session_id, object_storage_key)
raise
def task_run_has_slack_mapping(run_id: str | UUID, task_id: str | UUID, team_id: int) -> bool | None:
"""Whether a run is mapped to a Slack thread. ``None`` if the run isn't found."""
from products.slack_app.backend.models import ( # noqa: PLC0415 — cross-product import kept off the api import path
SlackThreadTaskMapping,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return SlackThreadTaskMapping.objects.filter(task_run=run).exists()
def task_run_is_terminal(run_id: str | UUID, task_id: str | UUID, team_id: int) -> bool | None:
"""Whether a run is in a terminal state. ``None`` if the run isn't found."""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return run.is_terminal
# --- Task run artifacts (S3 + manifest) ---
def _build_artifact_storage_path(run: TaskRun, artifact_id: str, name: str) -> tuple[str, str]:
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_safe_artifact_name,
)
safe_name = get_safe_artifact_name(name)
prefix = run.get_artifact_s3_prefix()
return safe_name, f"{prefix}/{artifact_id[:8]}_{safe_name}"
def _downloadable_artifact_entry(artifacts: list[dict[str, Any]] | None, artifact_id: str) -> dict[str, Any] | None:
entry = next((a for a in artifacts or [] if a.get("id") == artifact_id), None)
# Reference entries carry no file, so there is nothing to download for them.
return entry if entry is not None and entry.get("storage_path") else None
def _artifact_download_path(team_id: int, task_id: UUID, run_id: UUID, artifact_id: str) -> str:
return f"/api/projects/{team_id}/tasks/{task_id}/runs/{run_id}/artifacts/{artifact_id}/download/"
def _build_artifact_download_path(run: TaskRun, artifact_id: str) -> str:
return _artifact_download_path(run.team_id, run.task_id, run.id, artifact_id)
def _tag_artifact_object(run: TaskRun, storage_path: str) -> None:
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
try:
object_storage.tag(storage_path, {"ttl_days": "30", "team_id": str(run.team_id)})
except Exception as exc:
logger.warning(
"task_run.artifact_tag_failed",
extra={"task_run_id": str(run.id), "storage_path": storage_path, "error": str(exc)},
)
def _build_artifact_manifest_entry(
*,
artifact_id: str,
name: str,
artifact_type: str,
source: str,
size: int,
content_type: str,
storage_path: str,
uploaded_at: str,
script_sha256: str | None = None,
metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
entry: dict[str, Any] = {
"id": artifact_id,
"name": name,
"type": artifact_type,
"source": source,
"size": size,
"content_type": content_type,
"storage_path": storage_path,
"uploaded_at": uploaded_at,
}
if script_sha256 is not None:
entry[ARTIFACT_SCRIPT_SHA256_KEY] = script_sha256
if metadata:
entry["metadata"] = metadata
return entry
def _find_artifact_manifest_entry(manifest: list[dict], artifact_id: str, storage_path: str) -> dict | None:
return next(
(e for e in manifest if e.get("id") == artifact_id or e.get("storage_path") == storage_path),
None,
)
ARTIFACT_SCRIPT_HASH_BUDGET_BYTES = 64 * 1024 * 1024
def _earlier_versions_run_scripts(manifest: list[dict], name: str) -> bool:
return all(isinstance(e.get(ARTIFACT_SCRIPT_SHA256_KEY), str) for e in manifest if e.get("name") == name)
def _new_version_may_run_scripts(manifest: list[dict], name: str, base: dict | None, budget: int) -> tuple[bool, int]:
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
stored_bytes_match_digest,
)
if not _earlier_versions_run_scripts([*manifest, *([base] if base else [])], name):
return False, 0
previous = base or next((e for e in reversed(manifest) if e.get("name") == name), None)
if previous is None:
return True, 0
size = previous.get("size")
if not isinstance(size, int) or size > budget:
return False, 0
return stored_bytes_match_digest(previous.get("storage_path"), previous.get(ARTIFACT_SCRIPT_SHA256_KEY)), size
def _append_versions(manifest: list[dict], entries: list[dict]) -> list[dict]:
for entry in entries:
if ARTIFACT_SCRIPT_SHA256_KEY in entry and not _earlier_versions_run_scripts(manifest, entry["name"]):
del entry[ARTIFACT_SCRIPT_SHA256_KEY]
manifest.append(entry)
return manifest
def _save_artifact_manifest(run: TaskRun, manifest: list[dict]) -> None:
run.artifacts = manifest
run.save(update_fields=["artifacts", "updated_at"])
def get_user_attachment_max_size_bytes(name: str, content_type: str) -> int:
"""The largest file a user may attach to a task run, the same on every surface that attaches one."""
from products.tasks.backend.presentation.serializers import ( # noqa: PLC0415 — pure size helpers, kept off the api import path
get_task_run_artifact_max_size_bytes,
)
return get_task_run_artifact_max_size_bytes(name, content_type, "user_attachment")
def upload_task_run_artifacts(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
artifacts: list[dict],
uploaded_by: Literal["agent", "user"] | None = None,
written_with_open_network: bool = False,
) -> tuple[list[dict], list[dict]] | None:
"""Write artifact bytes to S3 and append them to the run manifest.
Returns ``(uploaded, manifest)`` — the entries created for ``artifacts`` and the full
manifest including them, each carrying a ``url`` — or ``None`` when the run isn't visible.
An artifact may carry an explicit ``id``; entries with that id are upserted into the
manifest (same-id S3 writes overwrite the same key), so callers that derive ids
deterministically get idempotent uploads under retries. Without an ``id`` each call
appends a fresh entry.
"""
import uuid as uuid_module # noqa: PLC0415
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
uploaded: list[dict] = []
hash_budget = ARTIFACT_SCRIPT_HASH_BUDGET_BYTES
for artifact in artifacts:
artifact_id = str(artifact.get("id") or uuid_module.uuid4().hex)
safe_name, storage_path = _build_artifact_storage_path(run, artifact_id, artifact["name"])
content_bytes = artifact["content_bytes"]
extras: dict[str, str] = {}
content_type = artifact.get("content_type")
if content_type:
extras["ContentType"] = content_type
may_run_scripts = written_with_open_network
if may_run_scripts and is_html_artifact(safe_name, content_type or ""):
may_run_scripts, spent = _new_version_may_run_scripts(
[*(run.artifacts or []), *uploaded], safe_name, None, hash_budget
)
hash_budget -= spent
script_sha256 = hashlib.sha256(content_bytes).hexdigest() if may_run_scripts else None
object_storage.write(storage_path, content_bytes, extras or None)
_tag_artifact_object(run, storage_path)
uploaded.append(
_build_artifact_manifest_entry(
artifact_id=artifact_id,
name=safe_name,
artifact_type=artifact["type"],
source=artifact.get("source") or "",
size=len(content_bytes),
content_type=content_type or "",
storage_path=storage_path,
uploaded_at=django_timezone.now().isoformat(),
script_sha256=script_sha256,
metadata=artifact.get("metadata"),
)
)
logger.info(
"task_run.artifact_uploaded",
extra={
"task_run_id": str(run.id),
"storage_path": storage_path,
"artifact_type": artifact["type"],
"size": len(content_bytes),
},
)
with transaction.atomic():
run = TaskRun.objects.select_for_update().get(pk=run.pk)
uploaded_ids = {entry["id"] for entry in uploaded}
manifest = _append_versions(
[entry for entry in (run.artifacts or []) if entry.get("id") not in uploaded_ids], uploaded
)
_save_artifact_manifest(run, manifest)
if uploaded_by == "agent":
_announce_agent_artifact_uploads(run, uploaded, manifest)
# Same download URL the finalize-upload path returns, so a caller that reaches storage
# through this endpoint instead of a presigned POST still gets a link to surface. Built
# after the save so it stays off the persisted manifest.
response_manifest = [
{**entry, "url": absolute_uri(_build_artifact_download_path(run, entry["id"]))}
if entry.get("id") and entry.get("storage_path")
else dict(entry)
for entry in manifest
]
return uploaded, response_manifest
# Each request is capped by the serializer, but entries accumulate across requests on
# one TaskRun.artifacts JSON value; without a total budget a caller could grow that row
# (and every later read of it) without bound.
MAX_RUN_REFERENCE_ARTIFACTS = 100
def register_task_run_posthog_references(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
references: list[dict[str, Any]],
caller_is_agent: bool = False,
acting_user_id: int | None = None,
) -> list[dict[str, Any]] | None:
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
# Only the task-bound sandbox identity is a verified agent; every other
# caller is recorded as themselves and posts no agent-authored thread event.
attribute_as_agent = caller_is_agent
created: list[dict[str, Any]] = []
with transaction.atomic():
run = TaskRun.objects.select_for_update().get(pk=run.pk)
manifest = [dict(entry) for entry in (run.artifacts or []) if isinstance(entry, dict)]
by_id = {str(entry.get("id")): entry for entry in manifest if entry.get("id")}
reference_count = sum(1 for entry in manifest if entry.get("type") == "reference")
now = django_timezone.now().isoformat()
manifest_changed = False
for reference in references:
object_kind = str(reference["object_kind"])
object_id = str(reference["object_id"])
source_message_id = str(reference["source_message_id"])
digest = hashlib.sha256(f"{object_kind}\0{object_id}".encode()).hexdigest()[:24]
artifact_id = f"phref_{digest}"
existing = by_id.get(artifact_id)
if existing is not None:
metadata = dict(existing.get("metadata") or {})
source_message_ids = list(metadata.get("source_message_ids") or [])
if source_message_id in source_message_ids or len(source_message_ids) >= 100:
continue
source_message_ids.append(source_message_id)
metadata["source_message_ids"] = source_message_ids
metadata["occurrence_count"] = len(source_message_ids)
existing["metadata"] = metadata
manifest_changed = True
continue
if reference_count >= MAX_RUN_REFERENCE_ARTIFACTS:
continue
reference_count += 1
name = re.sub(r"[\[\]\n]", " ", str(reference["name"])).strip()[:255] or object_id[:255]
entry = {
"id": artifact_id,
"name": name,
"type": "reference",
"source": "posthog_object",
"uploaded_at": now,
"uploaded_by": "agent" if attribute_as_agent else "user",
**({} if attribute_as_agent or acting_user_id is None else {"uploaded_by_user_id": acting_user_id}),
"metadata": {
"reference_type": "posthog_object",
"object_kind": object_kind,
"object_id": object_id,
"source_message_ids": [source_message_id],
"occurrence_count": 1,
},
}
manifest.append(entry)
by_id[artifact_id] = entry
created.append(entry)
manifest_changed = True
if manifest_changed:
_save_artifact_manifest(run, manifest)
for entry in created if attribute_as_agent else []:
reference_metadata = entry.get("metadata")
if not isinstance(reference_metadata, dict):
continue
post_artifact_thread_update(
run,
{
"id": entry["id"],
"name": entry["name"],
"artifact_type": entry["type"],
"reference_type": reference_metadata["reference_type"],
"object_kind": reference_metadata["object_kind"],
"current_version": 1,
},
revised=False,
)
return manifest
def prepare_task_run_artifact_uploads(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
artifacts: list[dict],
upload_expiration_seconds: int,
form_overhead_bytes: int,
) -> tuple[list[dict] | None, bool]:
"""Reserve S3 keys and presigned POST forms for direct artifact uploads.
Returns ``(prepared, ok)``: ``(None, _)`` when the run isn't found, ``(None, False)`` when a
presigned POST could not be generated, else ``(prepared, True)``.
"""
import uuid as uuid_module # noqa: PLC0415
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, True
prepared: list[dict] = []
for artifact in artifacts:
artifact_id = uuid_module.uuid4().hex
safe_name, storage_path = _build_artifact_storage_path(run, artifact_id, artifact["name"])
content_type = artifact.get("content_type") or ""
conditions: list[list[str | int]] = [["content-length-range", 0, artifact["size"] + form_overhead_bytes]]
presigned_post = object_storage.get_presigned_post(
storage_path, conditions=conditions, expiration=upload_expiration_seconds
)
if not presigned_post:
return None, False
prepared_artifact = {
"id": artifact_id,
"name": safe_name,
"type": artifact["type"],
"source": artifact.get("source") or "",
"size": artifact["size"],
"content_type": content_type,
"storage_path": storage_path,
"expires_in": upload_expiration_seconds,
"presigned_post": presigned_post,
}
if metadata := artifact.get("metadata"):
prepared_artifact["metadata"] = metadata
prepared.append(prepared_artifact)
return prepared, True
def finalize_task_run_artifact_uploads(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
artifacts: list[dict],
uploaded_by: Literal["agent", "user"],
uploaded_by_user_id: int | None,
written_with_open_network: bool = False,
) -> tuple[list[dict] | None, str | None]:
"""Verify directly-uploaded S3 objects and attach them to the run manifest.
``uploaded_by`` is server-derived and authoritative. ``source`` remains a client-declared organizational hint.
Returns ``(finalized_entries, error)``: ``(None, None)`` when the run isn't found,
``(None, error_message)`` on a validation failure, else ``(finalized_entries, None)``.
"""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_safe_artifact_name,
)
from products.tasks.backend.presentation.serializers import ( # noqa: PLC0415 — pure size helpers, kept off the api import path
build_task_run_artifact_size_error,
get_task_run_artifact_max_size_bytes,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
manifest = list(run.artifacts or [])
artifact_prefix = f"{run.get_artifact_s3_prefix()}/"
finalized_entries: list[dict] = []
new_entries: list[dict] = []
hash_budget = ARTIFACT_SCRIPT_HASH_BUDGET_BYTES
new_storage_paths: list[str] = []
for artifact in artifacts:
artifact_id = artifact["id"]
storage_path = artifact["storage_path"]
if not storage_path.startswith(artifact_prefix) or f"/{artifact_id[:8]}_" not in storage_path:
return None, "Artifact storage path is invalid for this run"
existing_entry = _find_artifact_manifest_entry(manifest, artifact_id, storage_path)
if existing_entry is not None:
finalized_entries.append(existing_entry)
continue
s3_object = object_storage.head_object(storage_path)
if not s3_object:
return None, "Artifact upload not found in object storage"
safe_name = get_safe_artifact_name(artifact["name"])
content_type = artifact.get("content_type") or s3_object.get("ContentType") or ""
content_length = s3_object.get("ContentLength")
if not isinstance(content_length, int):
return None, "Artifact upload metadata is unavailable"
max_size_bytes = get_task_run_artifact_max_size_bytes(safe_name, content_type, artifact.get("type"))
if content_length > max_size_bytes:
return None, build_task_run_artifact_size_error(safe_name, max_size_bytes)
script_sha256 = None
base_artifact_id = artifact.get("base_artifact_id")
base_entry = next((e for e in manifest if e.get("id") == base_artifact_id), None) if base_artifact_id else None
if (
written_with_open_network
and (base_artifact_id is None or base_entry is not None)
and is_html_artifact(safe_name, content_type)
and content_length <= hash_budget
):
may_run_scripts, spent = _new_version_may_run_scripts(
manifest, safe_name, base_entry, hash_budget - content_length
)
hash_budget -= content_length + spent
if may_run_scripts:
try:
uploaded_bytes = object_storage.read_bytes(storage_path, missing_ok=True)
except Exception:
logger.warning("task_run.artifact_script_hash_failed", extra={"task_run_id": str(run.id)})
uploaded_bytes = None
script_sha256 = hashlib.sha256(uploaded_bytes).hexdigest() if uploaded_bytes is not None else None
entry = _build_artifact_manifest_entry(
artifact_id=artifact_id,
name=safe_name,
artifact_type=artifact["type"],
source=artifact.get("source") or "",
size=content_length,
content_type=content_type,
storage_path=storage_path,
uploaded_at=django_timezone.now().isoformat(),
script_sha256=script_sha256,
metadata=artifact.get("metadata"),
)
entry["uploaded_by"] = uploaded_by
if uploaded_by == "user" and uploaded_by_user_id is not None:
entry["uploaded_by_user_id"] = uploaded_by_user_id
manifest.append(entry)
new_entries.append(entry)
finalized_entries.append(entry)
new_storage_paths.append(storage_path)
if new_entries:
# Re-read the manifest under the row lock rather than writing back the snapshot taken
# above: verifying the uploads does S3 I/O, and a dismissal that commits in that window
# would be silently reverted by a blind whole-array write.
with transaction.atomic():
locked_run = TaskRun.objects.select_for_update().get(pk=run.pk)
new_ids = {entry["id"] for entry in new_entries}
merged = _append_versions(
[entry for entry in (locked_run.artifacts or []) if entry.get("id") not in new_ids], new_entries
)
_save_artifact_manifest(locked_run, merged)
# Count versions from the locked merge, or a concurrent same-named finalize is missed.
manifest = merged
for storage_path in new_storage_paths:
_tag_artifact_object(run, storage_path)
if uploaded_by == "agent":
_announce_agent_artifact_uploads(run, new_entries, manifest)
# Attach a download URL per response entry so the caller (e.g. the upload_artifact
# tool) can surface a link to the file. The app URL redirects to a fresh presigned
# URL on each request, so unlike a raw presigned URL it stays short and works for
# the artifact's full retention window rather than one presign TTL; it is attached
# to the response only and never written back to the manifest.
response_entries: list[dict] = []
for entry in finalized_entries:
entry_id = entry.get("id")
response_entries.append(
{**entry, "url": absolute_uri(_build_artifact_download_path(run, entry_id))} if entry_id else dict(entry)
)
return response_entries, None
def list_task_run_living_artifacts(run_id: str | UUID, task_id: str | UUID, team_id: int) -> list[dict] | None:
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_task_artifacts_for_run,
serialize_task_artifact,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return [serialize_task_artifact(artifact) for artifact in get_task_artifacts_for_run(run)]
def get_task_run_living_artifact(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str | UUID
) -> dict | None:
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_task_artifact_for_run,
open_task_artifact,
serialize_task_artifact,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
artifact = get_task_artifact_for_run(run, artifact_id)
if artifact is None:
return None
serialized = serialize_task_artifact(artifact)
serialized["content"] = open_task_artifact(artifact)
return serialized
_LivingVersionResult = TypeVar("_LivingVersionResult")
def _task_run_living_artifact_version(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
artifact_id: str | UUID,
version: int,
load: Callable[[Any, int], _LivingVersionResult | None],
) -> tuple[_LivingVersionResult | None, str | None]:
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
LivingArtifactVersionTooLarge,
get_task_artifact_for_run,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
try:
UUID(str(artifact_id))
except ValueError:
return None, "not_found"
artifact = get_task_artifact_for_run(run, artifact_id)
if artifact is None:
return None, "not_found"
try:
result = load(artifact, version)
except LivingArtifactVersionTooLarge:
return None, "too_large"
except Exception:
logger.exception("Failed to read living artifact %s version %s for team %s", artifact_id, version, team_id)
return None, "read_failed"
if result is None:
return None, "not_found"
return result, None
def read_task_run_living_artifact_version(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str | UUID, version: int
) -> tuple[contracts.LivingArtifactVersionContent | None, str | None]:
"""Read the content of one living artifact version.
Returns ``(content, error)``: ``(None, None)`` if the run isn't found, ``(None, "not_found")`` if the
artifact or version isn't found or keeps no content, ``(None, "too_large")`` if a stored version is
over the preview limit, ``(None, "read_failed")`` if the storage read raised, else ``(content, None)``.
"""
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
read_living_artifact_version,
)
return _task_run_living_artifact_version(
run_id, task_id, team_id, artifact_id, version, read_living_artifact_version
)
def describe_task_run_living_artifact_version(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str | UUID, version: int
) -> tuple[contracts.LivingArtifactVersionPreview | None, str | None]:
"""Describe one living artifact version for a preview, without reading its stored bytes. Errors as in the read."""
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
describe_living_artifact_version,
)
return _task_run_living_artifact_version(
run_id, task_id, team_id, artifact_id, version, describe_living_artifact_version
)
def presign_task_run_living_artifact_version_download(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str | UUID, version: int
) -> contracts.LivingArtifactVersionDownload:
"""Presign a download URL for one stored living artifact version.
The error is ``"not_found"`` if the artifact or version isn't found, ``"not_stored"`` if the version
keeps its content as text, and ``"unavailable"`` if presigning fails. Both fields are None if the run
isn't found.
"""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_task_artifact_for_run,
resolve_living_artifact_version,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return contracts.LivingArtifactVersionDownload(url=None, error=None)
try:
UUID(str(artifact_id))
except ValueError:
return contracts.LivingArtifactVersionDownload(url=None, error="not_found")
artifact = get_task_artifact_for_run(run, artifact_id)
resolved = resolve_living_artifact_version(artifact, version) if artifact is not None else None
if artifact is None or resolved is None:
return contracts.LivingArtifactVersionDownload(url=None, error="not_found")
if not resolved.storage_path:
return contracts.LivingArtifactVersionDownload(url=None, error="not_stored")
url = object_storage.get_presigned_url(
resolved.storage_path,
content_type=resolved.content_type or None,
# Agent-written HTML or SVG must not render as a page, so the browser always saves it.
content_disposition=content_disposition_header(
as_attachment=True, filename=PurePosixPath(artifact.name).name or "artifact"
)
or "attachment",
)
if not url:
return contracts.LivingArtifactVersionDownload(url=None, error="unavailable")
return contracts.LivingArtifactVersionDownload(url=url, error=None)
def create_task_run_living_artifact(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
artifact: dict,
caller_is_agent: bool = False,
written_with_open_network: bool = False,
) -> tuple[dict | None, str | None]:
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
create_living_artifact,
serialize_task_artifact,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
try:
created = create_living_artifact(run=run, written_with_open_network=written_with_open_network, **artifact)
except Exception as exc:
logger.warning("Failed to create living artifact for task run %s: %s", run.id, exc)
return None, str(exc)
serialized = serialize_task_artifact(created)
if caller_is_agent:
post_artifact_thread_update(run, serialized, revised=False)
return serialized, None
def edit_task_run_living_artifact(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
caller_is_agent: bool = False,
written_with_open_network: bool = False,
artifact_id: str | UUID,
content: str | None = None,
content_bytes: bytes | None = None,
content_type: str | None = None,
source_artifact_id: str | None = None,
source_storage_path: str | None = None,
name: str | None = None,
metadata: dict | None = None,
) -> tuple[dict | None, str | None]:
from products.tasks.backend.logic.services.living_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
edit_living_artifact,
get_task_artifact_for_run,
serialize_task_artifact,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
artifact = get_task_artifact_for_run(run, artifact_id)
if artifact is None:
return None, "not_found"
try:
updated = edit_living_artifact(
artifact=artifact,
run=run,
content=content,
content_bytes=content_bytes,
content_type=content_type,
source_artifact_id=source_artifact_id,
source_storage_path=source_storage_path,
name=name,
metadata=metadata,
written_with_open_network=written_with_open_network,
)
except Exception as exc:
logger.warning("Failed to edit living artifact %s for task run %s: %s", artifact_id, run.id, exc)
return None, str(exc)
serialized = serialize_task_artifact(updated)
if caller_is_agent:
post_artifact_thread_update(run, serialized, revised=True)
return serialized, None
def presign_task_run_artifact(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, storage_path: str
) -> tuple[str | None, str | None]:
"""Presign a download URL for an artifact on the run.
Returns ``(url, error)``: ``(None, None)`` if the run isn't found, ``(None, "not_found")`` if
the artifact isn't on the run, ``(None, "unavailable")`` if presigning fails, else ``(url, None)``.
"""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
artifacts = run.artifacts or []
if not any(artifact.get("storage_path") == storage_path for artifact in artifacts):
return None, "not_found"
url = object_storage.get_presigned_url(storage_path)
if not url:
return None, "unavailable"
return url, None
def _without_dismissal(entry: dict) -> dict:
return {key: value for key, value in entry.items() if key != "dismissed_at"}
def set_task_run_artifacts_dismissed(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_ids: list[str], dismissed: bool
) -> tuple[list[dict] | None, str | None]:
"""Mark run artifacts as dismissed, or bring them back.
Dismissal is a ``dismissed_at`` stamp on the manifest entry rather than a delete: the object
stays in storage until its TTL expires, so a file dismissed by mistake can be restored.
Returns ``(manifest, error)``: ``(None, None)`` when the run isn't found, ``(None, "not_found")``
when an id isn't on the run, else ``(updated_manifest, None)``.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
with transaction.atomic():
locked_run = TaskRun.objects.select_for_update().get(pk=run.pk)
manifest = list(locked_run.artifacts or [])
requested = set(artifact_ids)
if not requested.issubset({entry.get("id") for entry in manifest}):
return None, "not_found"
# Restoring drops the key rather than nulling it, so a manifest entry only ever carries
# ``dismissed_at`` while it is dismissed and the response shape stays a plain optional.
dismissed_at = django_timezone.now().isoformat()
manifest = [
(
({**entry, "dismissed_at": dismissed_at} if dismissed else _without_dismissal(entry))
if entry.get("id") in requested
else entry
)
for entry in manifest
]
_save_artifact_manifest(locked_run, manifest)
return manifest, None
def presign_task_run_artifact_download(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str
) -> tuple[str | None, str | None]:
"""Presign a download URL for an artifact addressed by its manifest id.
Returns ``(url, error)``: ``(None, None)`` if the run isn't found, ``(None, "not_found")`` if
the artifact isn't on the run, ``(None, "unavailable")`` if presigning fails, else ``(url, None)``.
"""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None
entry = _downloadable_artifact_entry(run.artifacts, artifact_id)
if entry is None:
return None, "not_found"
filename = str(entry.get("name") or "artifact")
url = object_storage.get_presigned_url(
entry["storage_path"],
content_type=str(entry.get("content_type") or "") or None,
content_disposition=content_disposition_header(as_attachment=True, filename=filename) or "attachment",
)
if not url:
return None, "unavailable"
return url, None
def _run_has_open_network(run: TaskRun) -> bool:
environment = None
if (run.state or {}).get("sandbox_environment_id"):
environment = run.get_sandbox_environment()
if environment is None:
return False
profile = run.task.stored_profile
if profile is not None and (environment is None or environment.internal):
return profile.network.levels[0] == NetworkAccess.FULL
if environment is None:
return True
return (
environment.network_access_level == SandboxNetworkAccessLevel.FULL and environment.updated_at <= run.created_at
)
def sandbox_token_has_open_network(
team_id: int, token_id: UUID | int | str, *, task_id: UUID | str | None = None
) -> bool:
runs = TaskRun.objects.filter(team_id=team_id, state__sandbox_oauth_token_ids__contains=[str(token_id)])
if task_id is not None:
runs = runs.filter(task_id=task_id)
checked = False
for run in runs.select_related("task"):
if not _run_has_open_network(run):
return False
checked = True
return checked
def task_run_artifact_entry(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str
) -> dict[str, Any] | None:
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return next(
(
entry
for entry in run.artifacts or []
if entry.get("id") == artifact_id
and entry.get("storage_path")
and not entry.get("dismissed_at")
and (
(entry.get("type") == "output" and entry.get("uploaded_by") == "user")
or (entry.get("type") in ("output", "artifact") and entry.get("source") == "agent_output")
)
),
None,
)
def read_task_run_html_artifact(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_id: str
) -> bytes | None:
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
entry = task_run_artifact_entry(run_id, task_id, team_id, artifact_id=artifact_id)
if entry is None or not is_html_artifact(str(entry.get("name") or ""), str(entry.get("content_type") or "")):
return None
try:
return object_storage.read_bytes(str(entry["storage_path"]), missing_ok=True)
except Exception:
logger.exception("task_run.artifact_preview_read_failed", extra={"task_run_id": str(run_id)})
return None
def read_task_run_artifact(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, storage_path: str
) -> tuple[bytes | None, dict | None, str | None]:
"""Read artifact bytes for download, walking the resume chain.
Returns ``(content, artifact_entry, error)``. ``error`` is one of ``None`` (run not found),
``"not_found"`` (artifact not on the run/chain), ``"read_failed"`` (storage read raised), or
``"content_missing"`` (object absent). On success returns ``(content, artifact_entry, None)``.
"""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None, None, None
artifact = run.find_artifact_in_resume_chain(storage_path)
if artifact is None:
return None, None, "not_found"
try:
content = object_storage.read_bytes(storage_path, missing_ok=True)
except Exception:
logger.exception(
"task_run.artifact_download_failed",
extra={"task_run_id": str(run.id), "storage_path": storage_path},
)
return None, artifact, "read_failed"
if content is None:
return None, artifact, "content_missing"
return content, artifact, None
def analyze_task_run(run_id: str | UUID, task_id: str | UUID, team_id: int, *, user_id: int) -> tuple[str, bool] | None:
"""Create (or return the existing) PostHog-funded analysis task for a run.
Returns ``(analysis_task_id, created)``, or ``None`` when the run is not visible.
Raises ``TaskAnalysisError`` with a caller-safe message when the run cannot be analyzed
(for example, it has no log yet).
"""
from products.tasks.backend.logic.services.task_analysis import ( # noqa: PLC0415 — keep storage/temporal deps off the api import path
create_task_analysis,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
task = Task.objects.filter(id=run.task_id, team_id=team_id).first()
if task is None:
return None
analysis_task, created = create_task_analysis(team=task.team, user_id=user_id, target_task=task, target_run=run)
return str(analysis_task.id), created
def report_task_analysis_activity(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, activity: dict
) -> int | None:
"""Append one validated activity record to a run. Returns its index, or ``None`` if not visible."""
from products.tasks.backend.logic.services.task_analysis import ( # noqa: PLC0415 — keep storage deps off the api import path
append_analysis_activity,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return append_analysis_activity(run=run, activity=activity)
def read_task_run_logs(run_id: str | UUID, task_id: str | UUID, team_id: int) -> str | None:
"""Concatenated JSONL logs across the run's resume chain (oldest ancestor first)."""
log_urls = get_task_run_log_urls(run_id, task_id, team_id)
if log_urls is None:
return None
return read_task_run_log_content(log_urls)
_MARK_WATCHED_REDIS_TIMEOUT_SECONDS = 0.5
def mark_task_run_stream_watched(run_id: str | UUID, task_id: str | UUID, team_id: int) -> None:
from products.tasks.backend.logic.stream.redis_stream import ( # noqa: PLC0415 — keep redis off the api import path
TASK_RUN_STREAM_WATCHED_TIMEOUT,
get_task_run_stream_key,
get_task_run_stream_watched_key,
)
from products.tasks.backend.redis import ( # noqa: PLC0415 — keep redis off the api import path
get_tasks_stream_redis_sync,
run_uses_dedicated_stream,
)
info = get_task_run_stream_info(run_id, task_id, team_id)
if info is None or info.is_terminal or not run_stream_presence_gated(info.state):
return
try:
get_tasks_stream_redis_sync(
run_uses_dedicated_stream(info.state),
socket_timeout=_MARK_WATCHED_REDIS_TIMEOUT_SECONDS,
socket_connect_timeout=_MARK_WATCHED_REDIS_TIMEOUT_SECONDS,
).set(
get_task_run_stream_watched_key(get_task_run_stream_key(str(info.id))),
"1",
ex=TASK_RUN_STREAM_WATCHED_TIMEOUT,
)
except Exception:
logger.warning("task_run_stream_mark_watched_failed run_id=%s", info.id, exc_info=True)
_KEPT_TOOL_RESPONSE_FIELDS = ("decisionReason", "message")
def _drop_tool_response_copy(entry: object) -> bool:
notification = entry.get("notification") if isinstance(entry, dict) else None
params = notification.get("params") if isinstance(notification, dict) else None
update = params.get("update") if isinstance(params, dict) else None
meta = update.get("_meta") if isinstance(update, dict) else None
claude_code = meta.get("claudeCode") if isinstance(meta, dict) else None
if not isinstance(claude_code, dict) or "toolResponse" not in claude_code:
return False
tool_response = claude_code["toolResponse"]
kept = (
{key: tool_response[key] for key in _KEPT_TOOL_RESPONSE_FIELDS if isinstance(tool_response.get(key), str)}
if isinstance(tool_response, dict)
else {}
)
if kept:
claude_code["toolResponse"] = kept
else:
del claude_code["toolResponse"]
return True
def thread_view_of_log_content(log_content: str) -> str:
lines = log_content.split("\n")
for index, line in enumerate(lines):
if '"toolResponse"' not in line:
continue
try:
entry = json.loads(line)
except ValueError:
continue
if _drop_tool_response_copy(entry):
lines[index] = json.dumps(entry, separators=(",", ":"))
return "\n".join(lines)
def read_task_run_conversation_logs(run_id: str | UUID, task_id: str | UUID, team_id: int) -> str | None:
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
chain = run.get_history_chain()
if len(chain) < 2 or run.task.runtime != Task.Runtime.PI:
return read_task_run_log_content([ancestor.log_url for ancestor in chain])
contents = _TASK_LOG_READ_EXECUTOR.map(lambda ancestor: read_task_run_log_content([ancestor.log_url]), chain)
parts: list[str] = []
for ancestor, content in zip(chain, contents):
marker = {
"type": "pi_run_started",
"timestamp": ancestor.created_at.isoformat(),
"taskId": str(ancestor.task_id),
"runId": str(ancestor.id),
}
parts.append(json.dumps(marker) + "\n")
parts.append(content)
return "".join(parts)
_LOG_PART_SUMMARY_CACHE_SECONDS = 24 * 60 * 60
def _conversation_log_part_summary(log_url: str, entries: Callable[[], list[str]]) -> LogPartSummary:
"""A run log's summary, cached under one key per log with the object size it was made from. A log only grows,
so its size identifies its content, and a new size replaces the old summary. The cache is an optimization: a
cache error counts as a miss, and the summary comes from the log itself."""
from django.core.cache import cache # noqa: PLC0415 — keep cache setup off the api import path
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
head = object_storage.head_object(log_url)
size = int(head.get("ContentLength", 0)) if head else 0
if not size:
return summarize_log_part(entries())
# The cache pickles values, so it holds only a JSON string: the object size, then the summary.
key = f"tasks:log-part-summary:v5:{hashlib.sha256(log_url.encode()).hexdigest()}"
try:
cached = cache.get(key)
except Exception:
logger.warning("task_log_part_summary_cache_read_failed", exc_info=True)
cached = None
if isinstance(cached, str) and cached.startswith(f"{size}:"):
summary_hit = summary_from_json(cached.removeprefix(f"{size}:"))
if summary_hit is not None:
return summary_hit
summary = summarize_log_part(entries())
try:
cache.set(key, f"{size}:{summary_to_json(summary)}", timeout=_LOG_PART_SUMMARY_CACHE_SECONDS)
except Exception:
logger.warning("task_log_part_summary_cache_write_failed", exc_info=True)
return summary
def _conversation_log_parts(log_urls: list[str]) -> list[LogPart]:
"""The run logs of a resume chain as slice parts. The summaries load in parallel, and a part's entries load
only when the slice needs them."""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
def loader(log_url: str) -> Callable[[], list[str]]:
read: list[list[str]] = []
def entries() -> list[str]:
if not read:
read.append(log_entries(object_storage.read(log_url, missing_ok=True) or ""))
return read[0]
return entries
loaders = [loader(log_url) for log_url in log_urls]
pairs = list(zip(log_urls, loaders))
if len(pairs) == 1:
summaries = [_conversation_log_part_summary(*pairs[0])]
else:
summaries = list(_TASK_LOG_READ_EXECUTOR.map(lambda pair: _conversation_log_part_summary(*pair), pairs))
return [LogPart(summary=summary, entries=entries) for summary, entries in zip(summaries, loaders)]
def read_task_run_conversation_log_slice(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
tail_bytes: int,
before: int | None = None,
start: int | None = None,
) -> contracts.TaskRunLogSliceDTO | None:
"""Part of the conversation log, read from the run logs that overlap it.
With ``start``, every entry from that index to the end, or the latest turns when they are too many. Else the
latest turns that end before index ``before``, at least ``tail_bytes`` long. A Pi chain puts run markers
between its runs, so its indexes change when the chain grows: it returns the full log, not sliced.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
if run.task.runtime == Task.Runtime.PI:
content = read_task_run_conversation_logs(run_id, task_id, team_id)
if content is None:
return None
return contracts.TaskRunLogSliceDTO(content=content, offset=0, count=0, sliced=False)
chain = run.get_history_chain()
parts = _conversation_log_parts([ancestor.log_url for ancestor in chain])
if start is not None:
sliced = slice_log_parts_from(parts, start, tail_bytes)
else:
sliced = slice_log_parts_tail(parts, tail_bytes, before)
return contracts.TaskRunLogSliceDTO(
content=sliced.content,
offset=sliced.offset,
count=sliced.count,
preamble=sliced.preamble,
turns_before=sliced.turns_before,
origin=str(chain[0].id),
)
def get_task_run_log_urls(run_id: str | UUID, task_id: str | UUID, team_id: int) -> list[str] | None:
"""Log URLs across the run's resume chain (oldest ancestor first). ``None`` if the run isn't found."""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return [ancestor.log_url for ancestor in run.get_resume_chain()]
def get_task_run_log_size(log_urls: list[str], *, strict: bool = False) -> int:
"""Total byte size of the given log objects, without downloading them. Storage-only: safe off the request thread."""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
def _size(log_url: str) -> int:
head = object_storage.head_object_strict(log_url) if strict else object_storage.head_object(log_url)
return int(head.get("ContentLength", 0)) if head else 0
if len(log_urls) == 1:
return _size(log_urls[0])
return sum(_TASK_LOG_READ_EXECUTOR.map(_size, log_urls))
def read_task_run_log_content(log_urls: list[str]) -> str:
"""Concatenated JSONL content for the given log URLs. Storage-only: safe off the request thread."""
from posthog.storage import object_storage # noqa: PLC0415 — keep storage deps off the api import path
chunks: Iterable[str]
if len(log_urls) == 1:
chunks = [object_storage.read(log_urls[0], missing_ok=True) or ""]
else:
chunks = _TASK_LOG_READ_EXECUTOR.map(
lambda log_url: object_storage.read(log_url, missing_ok=True) or "", log_urls
)
parts: list[str] = []
for chunk in chunks:
if chunk:
if not chunk.endswith("\n"):
chunk = chunk + "\n"
parts.append(chunk)
return "".join(parts)
def parse_task_run_log_entries(log_content: str) -> Iterator[dict]:
"""The JSON objects in a JSONL log, skipping blank and malformed lines."""
for log_line in log_content.splitlines():
log_line = log_line.strip()
if not log_line:
continue
try:
parsed_line = json.loads(log_line)
except json.JSONDecodeError:
continue
if isinstance(parsed_line, dict):
yield parsed_line
def _read_run_stream_entries(run: TaskRun) -> list[dict]:
from products.tasks.backend.logic.stream.redis_stream import ( # noqa: PLC0415 — keep redis off the api import path
DATA_KEY,
get_task_run_stream_key,
)
from products.tasks.backend.redis import ( # noqa: PLC0415 — keep redis off the api import path
get_tasks_stream_redis_sync,
run_uses_dedicated_stream,
)
try:
client = get_tasks_stream_redis_sync(run_uses_dedicated_stream(run.state))
raw_entries = client.xrange(get_task_run_stream_key(str(run.id)))
except Exception:
logger.warning("task_run_stream_read_failed run_id=%s", run.id, exc_info=True)
return []
entries: list[dict] = []
for _stream_id, fields in raw_entries:
raw = fields.get(DATA_KEY) if isinstance(fields, dict) else None
if raw is None:
continue
try:
parsed = json.loads(raw)
except (json.JSONDecodeError, TypeError):
continue
if isinstance(parsed, dict):
entries.append(parsed)
return entries
def read_task_run_stream_entries(run_id: str | UUID, task_id: str | UUID, team_id: int) -> list[dict]:
"""Every frame still held in the run's live Redis stream, oldest first.
The stream is capped and expires after the run ends, so a caller that needs the whole history
uses ``read_task_run_history``. Returns an empty list when the run is not visible or the
stream is gone.
"""
run = _get_visible_run(run_id, task_id, team_id)
return _read_run_stream_entries(run) if run is not None else []
_USER_PROMPT_METHODS = frozenset({"_posthog/user_message", "session/prompt"})
def _holds_user_prompt(entries: list[dict]) -> bool:
for entry in entries:
notification = entry.get("notification") if entry.get("type") == "notification" else None
if isinstance(notification, dict) and notification.get("method") in _USER_PROMPT_METHODS:
return True
return False
def _server_notification_key(entry: dict) -> str | None:
# A persisted server notification carries no event id, but both stores hold the same timestamped event.
notification = entry.get("notification") if entry.get("type") == "notification" else None
method = notification.get("method") if isinstance(notification, dict) else None
if entry.get("event_id") or not isinstance(method, str) or not method.startswith("_posthog/"):
return None
return json.dumps(entry, sort_keys=True)
def _overlap_with_log_tail(log_entries: list[dict], stream_entries: list[dict]) -> int:
"""How many leading stream entries the log already holds, as the tail it ends with."""
if not stream_entries:
return 0
first = stream_entries[0]
for start in range(max(0, len(log_entries) - len(stream_entries)), len(log_entries)):
size = len(log_entries) - start
if log_entries[start] == first and log_entries[start:] == stream_entries[:size]:
return size
return 0
def _entry_time(entry: dict) -> datetime | None:
try:
parsed = datetime.fromisoformat(entry["timestamp"])
except (KeyError, TypeError, ValueError):
return None
return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
def _merge_by_timestamp(entries: list[dict], extra: list[dict]) -> list[dict]:
"""Slots each of ``extra`` in before the first of ``entries`` stamped later, keeping both orders."""
merged: list[dict] = []
pending = list(extra)
for entry in entries:
entry_time = _entry_time(entry)
while pending and entry_time is not None and (pending_time := _entry_time(pending[0])) is not None:
if pending_time > entry_time:
break
merged.append(pending.pop(0))
merged.append(entry)
return [*merged, *pending]
def read_task_run_history(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, max_bytes: int
) -> list[dict] | None:
"""Every frame of the conversation across the run's resume chain, oldest first.
The logs hold every run, and the run's live stream adds what its log has not caught up with
yet. The agent stamps one event id in both stores, so a stream entry the logs already cover is
dropped, the way the thread's stream view merges them. An agent that stamps no ids keeps the
whole run in an untrimmed stream, which then stands in for the run's own log, apart from the
server notifications that only the log holds.
Returns ``None`` without downloading any log when the logs to read are over ``max_bytes``, and
an empty list when the run is not visible.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return []
log_urls = [ancestor.log_url for ancestor in run.get_resume_chain()]
from products.tasks.backend.logic.stream.redis_stream import ( # noqa: PLC0415 — keep redis off the api import path
TASK_RUN_STREAM_MAX_LENGTH,
)
stream_entries = _read_run_stream_entries(run)
# A stream at the length cap may have lost its head to the trim, so only a shorter one can stand in for the log.
stream_is_whole_run = (
len(stream_entries) < TASK_RUN_STREAM_MAX_LENGTH
and not any(entry.get("event_id") for entry in stream_entries)
and _holds_user_prompt(stream_entries)
)
if log_urls and get_task_run_log_size(log_urls) > max_bytes:
return None
if stream_is_whole_run:
earlier_entries = (
list(parse_task_run_log_entries(read_task_run_log_content(log_urls[:-1]))) if log_urls[:-1] else []
)
# A server notification can reach the log after its live write failed or was skipped for want of a watcher.
streamed = {_server_notification_key(entry) for entry in stream_entries}
persisted_only = [
entry
for entry in parse_task_run_log_entries(read_task_run_log_content(log_urls[-1:]))
if (key := _server_notification_key(entry)) is not None and key not in streamed
]
return [*earlier_entries, *_merge_by_timestamp(stream_entries, persisted_only)]
log_entries = list(parse_task_run_log_entries(read_task_run_log_content(log_urls))) if log_urls else []
if not any(entry.get("event_id") for entry in stream_entries):
# Without ids the backlog index matches nothing, so the log's catch-up of the stream is cut by position.
stream_entries = stream_entries[_overlap_with_log_tail(log_entries, stream_entries) :]
backlog = TaskRunStreamBacklogIndex(log_entries)
persisted_server_notifications = {
key for key in (_server_notification_key(entry) for entry in log_entries) if key is not None
}
uncovered = [
entry
for entry in stream_entries
if not backlog.covers(entry) and _server_notification_key(entry) not in persisted_server_notifications
]
# A live-only server notification can predate log frames, so it goes back to its place in time.
live_only = [entry for entry in uncovered if _server_notification_key(entry) is not None]
tail = [entry for entry in uncovered if _server_notification_key(entry) is None]
return _merge_by_timestamp([*log_entries, *tail], live_only)
def publish_task_run_stream_notification(
run_id: str | UUID, task_id: str | UUID, team_id: int, method: str, params: dict, *, persist: bool = True
) -> contracts.StreamNotificationDelivery:
"""Write a server-originated ``_posthog/*`` notification to the run's live stream, and to its S3
log unless ``persist`` is off.
The live write reaches connected threads the way an agent-server frame would; the log append is
what a later bootstrap replays, so the frame survives the stream's expiry. A persisted frame is
written live only after the log append succeeds, so a thread never shows a frame that a reload
loses. A frame that only matters to threads open right now skips the log, which is a rewrite of
the whole object. The result reports each leg, so a caller can decide which one it needs.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return contracts.StreamNotificationDelivery(live=False, persisted=False)
event = run.build_notification_event(method, params)
if persist:
try:
run.append_log([event], lock_attempts=1)
except Exception:
logger.warning("task_run_stream_notification_log_append_failed run_id=%s", run_id, exc_info=True)
return contracts.StreamNotificationDelivery(live=False, persisted=False)
live = run.publish_stream_event(event) is not None
return contracts.StreamNotificationDelivery(live=live, persisted=persist)
def create_task_run_connection_token(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, user_id: int, distinct_id: str
) -> str | None:
"""Mint a sandbox connection token for a run. ``None`` if the run isn't found."""
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415 — keep sandbox deps off the api import path
create_sandbox_connection_token as _create,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return _create(task_run=run, user_id=user_id, distinct_id=distinct_id)
def create_task_run_stream_read_token(run_id: str | UUID, task_id: str | UUID, team_id: int) -> str | None:
"""Mint a run-scoped token for reading a run's live event stream. ``None`` if the run isn't found."""
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415 — keep sandbox deps off the api import path
create_stream_read_token as _create,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
return _create(task_run=run)
def task_uses_pi_runtime(task_id: str | UUID, team_id: int) -> bool:
return Task.objects.filter(id=task_id, team_id=team_id, runtime=Task.Runtime.PI).exists()
def task_is_one_shot_analysis(task_id: str | UUID, team_id: int) -> bool:
"""Whether this task is a server-created analysis, which accepts no further runs.
Analysis generations are excluded from the customer's credit rollup by their task origin,
so a second run under the same task would be unbilled model time for any prompt its owner
sends. The run the server created is the whole task.
"""
return Task.objects.filter(id=task_id, team_id=team_id, origin_product=Task.OriginProduct.TASK_ANALYSIS).exists()
def resolve_stream_base_url() -> str | None:
"""Agent-proxy base URL for the read leg, or ``None`` to read from Django directly.
The server owns this decision; clients just connect to whatever URL comes back.
"""
return settings.TASKS_AGENT_PROXY_PUBLIC_URL or None
# --- Task run commands (user_message signal + sandbox proxy) ---
class PermissionResponseUnavailable(Exception):
def __init__(self, *, target_ended: bool) -> None:
self.code = "permission_target_ended" if target_ended else "agent_session_not_ready"
self.status_code = 409 if target_ended else 503
super().__init__("This run has ended." if target_ended else "The agent is still starting. Please try again.")
def validate_permission_response_target(run_id: str | UUID, task_id: str | UUID, team_id: int) -> None:
run = _get_visible_run(run_id, task_id, team_id)
if run is None or run.is_terminal:
raise PermissionResponseUnavailable(target_ended=True)
def classify_permission_response(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, status_code: int, data: object
) -> bool:
from products.tasks.backend.logic.services.agent_command import ( # noqa: PLC0415
is_agent_session_not_ready,
permission_response_succeeded,
)
validate_permission_response_target(run_id, task_id, team_id)
if is_agent_session_not_ready(status_code, data):
raise PermissionResponseUnavailable(target_ended=False)
return 200 <= status_code < 300 and permission_response_succeeded(data)
def validate_task_run_artifact_ids(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, artifact_ids: list[str]
) -> tuple[list[str], bool]:
"""Resolve artifact ids for a run. Returns ``(missing_ids, found)``; ``found=False`` if the run isn't found."""
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_task_run_artifacts_by_id,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return [], False
_, missing_artifact_ids = get_task_run_artifacts_by_id(run, artifact_ids)
return missing_artifact_ids, True
def signal_task_run_user_message(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
content: str | None,
artifact_ids: list[str],
actor_user_id: int | None = None,
message_id: str | None = None,
actor_slack_user_id: str | None = None,
person_message: str | None = None,
steer: bool = False,
rpc_timeout: timedelta | None = None,
workflow_id: str | None = None,
plan_owner_consented: bool = False,
) -> bool | None:
"""Queue a user_message follow-up signal on the run's workflow.
``plan_owner_consented`` lets someone other than the plan owner message a run on the owner's
plan. Only a caller that collected the owner's consent may set it, such as the Slack app,
where the thread creator chooses who may join their threads.
Returns ``True`` on success, ``False`` when the target workflow is gone
(completed or evicted — a terminal outcome), ``None`` when the run isn't
found. Transient signalling failures propagate so a calling Temporal
activity retries rather than reporting a dead end to the user.
"""
from temporalio.service import RPCError, RPCStatusCode # noqa: PLC0415 — keep temporalio off the api import path
from products.tasks.backend.exceptions import (
ComputeBillingLimitError, # noqa: PLC0415 — keep temporalio off the api import path
SandboxNotFoundError,
)
from products.tasks.backend.temporal.client import ( # noqa: PLC0415 — keep temporalio off the api import path
signal_task_followup_message,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
if not plan_owner_consented:
ensure_subscription_owner(run.state, actor_user_id)
if run.is_terminal or (run.state or {}).get("cancel_requested_at"):
if not run.is_terminal:
raise RuntimeError("Task run is still stopping. Try again shortly.")
sandbox_id = (run.state or {}).get("sandbox_id")
if sandbox_id:
try:
sandbox = get_sandbox_class_for_sandbox_id(sandbox_id).get_by_id(sandbox_id)
if sandbox.is_running():
raise RuntimeError("Task run is still stopping. Try again shortly.")
except SandboxNotFoundError:
pass
return False
from products.tasks.backend.logic.services.compute_quota import get_compute_quota_denial_reason # noqa: PLC0415
if reason := get_compute_quota_denial_reason(run.task):
raise ComputeBillingLimitError({"team_id": team_id, "task_id": str(task_id), "run_id": str(run_id)}, reason)
accepted_at = django_timezone.now()
try:
context_values = {"actor_slack_user_id": actor_slack_user_id, "person_message": person_message}
context = {key: value for key, value in context_values.items() if value} or None
signal_task_followup_message(
workflow_id or run.workflow_id,
content,
artifact_ids,
message_id,
actor_user_id,
context,
steer=steer,
**({"rpc_timeout": rpc_timeout} if rpc_timeout is not None else {}),
)
except RPCError as e:
if e.status == RPCStatusCode.NOT_FOUND:
if not run.is_terminal and (run.state or {}).get("await_user_message"):
raise
logger.warning("Follow-up signal target workflow gone for task run %s", run.id)
return False
raise
if message_id and content and content.strip():
try:
run.record_pending_followup_message(message_id, content, accepted_at=accepted_at)
except Exception:
logger.warning("Failed to record pending follow-up message for task run %s", run.id, exc_info=True)
return True
def apply_task_run_model_config(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
model: str | None = None,
reasoning_effort: str | None = None,
actor_user_id: int | None = None,
) -> bool:
"""Switch a live run's model and/or reasoning effort on its agent server.
The runtime adapter is not switchable — it is the harness process the sandbox was
started with — so the model has to belong to the adapter the run is already on; the
agent-server rejects anything else outright. Returns whether every requested change
landed, and writes the ones that did back to ``state`` so readers of the run agree
with what the sandbox is actually running.
Model first, then effort: which efforts exist depends on the model, and the
agent-server rebuilds its effort options the moment the model changes.
"""
from products.tasks.backend.logic.services.agent_command import ( # noqa: PLC0415 — keep sandbox deps off the api import path
send_set_config_option,
)
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415 — keep sandbox deps off the api import path
create_sandbox_connection_token,
)
from products.tasks.backend.logic.services.run_actor import ( # noqa: PLC0415 — keep sandbox deps off the api import path
get_actor_distinct_id,
)
# (agent-server option id, value, run-state key), in the order they must be sent.
requested = [
(config_id, value, state_key)
for config_id, value, state_key in (("model", model, "model"), ("effort", reasoning_effort, "reasoning_effort"))
if value
]
if not requested:
return False
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return False
actor = User.objects.filter(id=actor_user_id).first() if actor_user_id else None
distinct_id = get_actor_distinct_id(actor) if actor else None
if model and get_model_access_error(model, distinct_id=distinct_id) is not None:
# The entitlement check the run-create path applies, so a follow-up can't reach a
# gated model the caller could not have started the run on.
logger.warning("Model access denied switching task run %s to %s", run.id, model)
return False
if model and not pinned_run_allows_model(run.state, model):
# A gateway denial does not fall back, so an off-pin model fails every turn.
logger.warning("Model %s is outside the gateway pin of task run %s", model, run.id)
return False
auth_token = (
create_sandbox_connection_token(run, user_id=actor.id, distinct_id=distinct_id)
if actor and actor.id and distinct_id
else None
)
applied: dict[str, Any] = {}
for config_id, value, state_key in requested:
result = send_set_config_option(run, config_id, value, auth_token=auth_token)
if not result.success:
logger.warning("Failed to set %s=%s on task run %s: %s", config_id, value, run.id, result.error)
break
applied[state_key] = value
if applied:
TaskRun.update_state_atomic(run.id, updates=applied)
return len(applied) == len(requested)
def task_run_model_outside_gateway_pin(
run_id: str | UUID, task_id: str | UUID, team_id: int, model: str | None
) -> bool:
run = _get_visible_run(run_id, task_id, team_id)
return run is not None and not pinned_run_allows_model(run.state, model)
def get_task_run_sandbox_connection(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, user_id: int, distinct_id: str
) -> contracts.TaskRunSandboxConnectionDTO | None:
"""Sandbox connection details for proxying a command. ``None`` if the run isn't found.
``sandbox_url`` is ``None`` when the run has no active sandbox (no connection token is minted
in that case).
"""
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415 — keep sandbox deps off the api import path
create_sandbox_connection_token as _create,
)
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
parse_run_state,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
run_state = parse_run_state(run.state)
if not run_state.sandbox_url:
return contracts.TaskRunSandboxConnectionDTO(
sandbox_url=None, sandbox_connect_token=None, run_is_terminal=run.is_terminal
)
from products.tasks.backend.logic.services.agent_command import ( # noqa: PLC0415 — keep sandbox deps off the api import path
sandbox_transport_token,
)
connection_token = _create(task_run=run, user_id=user_id, distinct_id=distinct_id)
transport_token, token_param = sandbox_transport_token(run.state, run_state.sandbox_url)
return contracts.TaskRunSandboxConnectionDTO(
sandbox_url=run_state.sandbox_url,
sandbox_connect_token=transport_token,
connection_token=connection_token,
sandbox_token_param=token_param,
run_is_terminal=run.is_terminal,
)
TaskRunPreviewOutcome = Literal["ready", "not_ready", "ended", "unavailable"]
@frozen
class TaskRunPreviewRedirect:
outcome: TaskRunPreviewOutcome
redirect_url: str | None = field(default=None, repr=False)
_PREVIEW_NOT_READY = TaskRunPreviewRedirect(outcome="not_ready")
_PREVIEW_ENDED = TaskRunPreviewRedirect(outcome="ended")
_PREVIEW_UNAVAILABLE = TaskRunPreviewRedirect(outcome="unavailable")
_PREVIEW_HEALTH_PROBE = (
"curl -sf --max-time 5 http://localhost:8010/_health >/dev/null"
f" && curl -sf --max-time 5 http://127.0.0.1:{DEV_STACK_PREVIEW_PORT}/@vite/client >/dev/null"
)
_PREVIEW_HEALTH_PROBE_TIMEOUT_SECONDS = 20
def task_run_preview_ready(state: dict | None) -> bool:
run_state = state or {}
preview = run_state.get(DEV_STACK_PREVIEW_STATE_KEY)
if not isinstance(preview, dict):
return False
port = preview.get("port")
if isinstance(port, bool) or port != DEV_STACK_PREVIEW_PORT:
return False
sandbox_id = run_state.get("sandbox_id")
return bool(sandbox_id) and preview.get("sandbox_id") == sandbox_id
def resolve_task_run_preview_redirect(
run_id: str | UUID, task_id: str | UUID, team_id: int, *, user_id: int
) -> TaskRunPreviewRedirect | None:
from products.tasks.backend.exceptions import (
SandboxNotFoundError, # noqa: PLC0415 — keep temporalio off the api import path
)
from products.tasks.backend.logic.services.sandbox import ( # noqa: PLC0415 — keeps the sandbox providers off the api import path
get_sandbox_class,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return None
state = run.state if isinstance(run.state, dict) else {}
if not task_run_preview_ready(state):
return _PREVIEW_NOT_READY
sandbox_id = state["sandbox_id"]
try:
sandbox = get_sandbox_class().get_by_id(str(sandbox_id))
running = sandbox.is_running()
except SandboxNotFoundError:
return _PREVIEW_ENDED
except Exception:
logger.exception("task_run_preview_sandbox_lookup_failed", extra={"run_id": str(run.id)})
return _PREVIEW_UNAVAILABLE
if not running:
return _PREVIEW_ENDED
try:
probe = sandbox.execute(_PREVIEW_HEALTH_PROBE, timeout_seconds=_PREVIEW_HEALTH_PROBE_TIMEOUT_SECONDS)
except SandboxNotFoundError:
return _PREVIEW_ENDED
except Exception:
logger.exception("task_run_preview_health_probe_failed", extra={"run_id": str(run.id)})
return _PREVIEW_UNAVAILABLE
if probe.exit_code != 0:
return _PREVIEW_UNAVAILABLE
try:
credentials = sandbox.create_preview_connect_credentials(
port=DEV_STACK_PREVIEW_PORT, user_metadata={"user_id": user_id, "team_id": team_id}
)
except SandboxNotFoundError:
return _PREVIEW_ENDED
except Exception:
logger.exception("task_run_preview_token_mint_failed", extra={"run_id": str(run.id)})
return _PREVIEW_UNAVAILABLE
if not credentials.token:
return _PREVIEW_UNAVAILABLE
return TaskRunPreviewRedirect(
outcome="ready",
redirect_url=f"{credentials.url.rstrip('/')}/?_modal_connect_token={credentials.token}",
)
def is_hogland_sandbox_url(sandbox_url: str | None) -> bool:
"""Whether ``sandbox_url`` is the configured hogland control-plane origin.
Thin facade wrapper: presentation may not import ``logic`` directly (see
products/architecture.md § Presentation Layer), so both the sandbox-URL allowlist gate
and the request-transport decision in the command relay view go through this one edge
instead of reaching into ``logic.services.agent_command`` themselves.
"""
from products.tasks.backend.logic.services.agent_command import ( # noqa: PLC0415 — keep sandbox deps off the api import path
is_hogland_sandbox_url as _is_hogland_sandbox_url,
)
return _is_hogland_sandbox_url(sandbox_url)
# Relay control verbs whose outcome PostHog AI funnels track. Captured here (gated on
# origin_product) so the generic relay stays product-agnostic while the conversation layer stops
# firing them as the renderer drives permission/cancel through `runs/{run}/command/`.
_POSTHOG_AI_RELAY_TELEMETRY_METHODS: frozenset[str] = frozenset({"cancel", "permission_response"})
def capture_relay_command_telemetry(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
method: str,
params: dict | None,
success: bool,
) -> None:
"""Emit PostHog AI control-verb telemetry for a relayed agent command.
Preserves the ``task_run_cancelled`` / ``permission_responded`` funnels once the renderer moves
permission/cancel onto the generic relay. ``conversation_id`` is intentionally null (the relay
has no conversation); ``TaskRun.capture_event`` stamps ``origin_product``/``run_id`` so
generic-task usage stays out of the PostHog AI funnels. Mirrors the old conversation-layer
semantics: a cancel is recorded only when it actually reached the agent, while a permission
response is recorded with its forward ``success`` either way.
"""
if method not in _POSTHOG_AI_RELAY_TELEMETRY_METHODS:
return
run = _get_visible_run(run_id, task_id, team_id)
if run is None or run.task.origin_product != Task.OriginProduct.POSTHOG_AI:
return
params = params or {}
if method == "cancel":
if not success:
return
run.capture_event(
"task_run_cancelled",
{
"execution_type": "sandbox",
"surface": "relay",
"conversation_id": None,
"cancel_source": "user",
},
)
return
run.capture_event(
"permission_responded",
{
"execution_type": "sandbox",
"surface": "relay",
"conversation_id": None,
"request_id": params.get("requestId"),
"option_id": params.get("optionId"),
"success": success,
},
)
# --- Task run relay (Slack) ---
def _pick_relay_text(*, text: str, text_parts: list[str] | None) -> str:
"""Pick the text to post. If ``text_parts`` has any non-empty entries,
the last one wins (that's the post-last-tool-use answer). Otherwise fall
back to the joined ``text`` field."""
if text_parts:
for part in reversed(text_parts):
if isinstance(part, str) and part.strip():
return part
return text
def relay_task_run_message(
run_id: str | UUID,
task_id: str | UUID,
team_id: int,
*,
text: str,
text_parts: list[str] | None = None,
message_id: str | None = None,
trace_id: str | None = None,
) -> tuple[str, str | None]:
"""Queue a Slack relay workflow for a run message, or under the agent-design
flag give the running task workflow the text as the turn's final answer.
Returns ``(status, relay_id)`` where status is ``"accepted"`` (relay_id set), ``"skipped"``
(run not found / terminal / no Slack mapping / empty text / streamed inline under the
agent-design flag), or ``"failed"``.
When ``text_parts`` is provided the last non-empty entry is used — it's the
post-last-tool-use answer, and posting only that keeps the interim narration
("Let me check…") out of the Slack thread. Older callers still send just
``text`` and get the previous behavior unchanged.
``trace_id`` is the gateway trace id of the turn that wrote this answer, which the
posted reply keeps so a rating on it can name the turn. Absent when the sandbox
reported none.
"""
from products.slack_app.backend.models import ( # noqa: PLC0415 — cross-product import kept off the api import path
SlackThreadTaskMapping,
)
from products.tasks.backend.temporal.client import ( # noqa: PLC0415 — keep temporalio off the api import path
execute_posthog_code_agent_relay_workflow,
signal_agent_final_text,
)
from products.tasks.backend.temporal.process_task.activities.feature_flags import ( # noqa: PLC0415 — keep temporal off the api import path
AGENT_DESIGN_STATE_KEY,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None or run.is_terminal:
return "skipped", None
if not SlackThreadTaskMapping.objects.filter(task_run=run).exists():
return "skipped", None
posted_text = _pick_relay_text(text=text, text_parts=text_parts)
trimmed = posted_text.strip()
if not trimmed:
return "skipped", None
if bool((run.state or {}).get(AGENT_DESIGN_STATE_KEY)):
try:
signal_agent_final_text(run.workflow_id, trimmed, trace_id)
except Exception:
logger.exception("task_run_relay_text_signal_failed", extra={"run_id": str(run.id)})
return "skipped", None
try:
relay_id = execute_posthog_code_agent_relay_workflow(
run_id=str(run.id),
text=trimmed,
delete_progress=True,
message_id=message_id,
trace_id=trace_id,
offer_reply_suggestions=True,
offer_feature_tip=True,
)
except Exception:
logger.exception("task_run_relay_message_enqueue_failed", extra={"run_id": str(run.id)})
return "failed", None
return "accepted", relay_id
# --- Task run creation / start / cloud resume ---
def user_can_author_repository(user_id: int, repository: str) -> bool:
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
get_user_github_integration,
user_github_integration_is_usable,
)
user = User.objects.filter(id=user_id).first()
integration = get_user_github_integration(user, repository=repository, allow_refresh=False)
return user_github_integration_is_usable(integration)
def user_has_usable_personal_github(user_id: int) -> bool:
"""Whether the user's personal GitHub integration can produce a usable token, ignoring repo access.
Mirrors the usability checks in `UserGitHubIntegration.get_usable_user_access_token`
(missing user access token, expired refresh token) without the network refresh or the
row deletion that path performs, so callers can gate before a run reaches the credential
path rather than failing partway through it.
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
get_user_github_integration,
user_github_integration_is_usable,
)
user = User.objects.filter(id=user_id).first()
integration = get_user_github_integration(user, allow_refresh=False)
return user_github_integration_is_usable(integration)
def _ensure_task_team_github_integration(task: Task) -> bool:
if task.github_integration_id is not None:
return True
github_integration = IntegrationManager.github.oauth.find(task.team_id)
if github_integration is None:
return False
task.github_integration_id = github_integration.id
task.save(update_fields=["github_integration", "updated_at"])
return True
def _resolve_cloud_pr_authorship_mode(
task: Task,
*,
pr_authorship_mode,
request_user_id: int | None,
github_user_token: str | None,
):
"""Resolve the effective PR-authorship mode for a cloud run.
Returns ``(mode, error)``: ``error`` is a ``TaskRunValidationError`` when authorship can't be
established (mode is then ``None``); otherwise ``error`` is ``None`` and ``mode`` is the
resolved value. Mirrors the original view helper exactly.
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
PrAuthorshipMode,
resolve_user_github_integration_for_task,
user_github_integration_is_usable,
)
if not Task._github_resolution_allowed(
task.origin_product, has_repository=bool(task.repositories or task.repository)
):
if pr_authorship_mode == PrAuthorshipMode.USER:
return None, contracts.TaskRunValidationError(
kind="validation_error",
code="github_authorization_required",
detail="User-authored runs are not allowed for this task without a repository.",
attr="pr_authorship_mode",
)
return None, None
if task.github_access_limit == GithubAccess.NONE:
return PrAuthorshipMode.BOT, None
if pr_authorship_mode != PrAuthorshipMode.USER or github_user_token:
return pr_authorship_mode, None
if task.created_by_id != request_user_id:
return None, contracts.TaskRunValidationError(
kind="validation_error",
code="github_authorization_required",
detail="User-authored runs must be started by the task creator, or provide github_user_token.",
attr="pr_authorship_mode",
)
user_github_integration = resolve_user_github_integration_for_task(task, allow_refresh=False)
if user_github_integration is not None and user_github_integration_is_usable(user_github_integration):
if task.github_user_integration_id != user_github_integration.integration.id:
task.github_user_integration = user_github_integration.integration
task.save(update_fields=["github_user_integration", "updated_at"])
return PrAuthorshipMode.USER, None
if _ensure_task_team_github_integration(task) or task.origin_product == Task.OriginProduct.POSTHOG_AI:
return PrAuthorshipMode.BOT, None
return None, contracts.TaskRunValidationError(
kind="validation_error",
code="github_authorization_required",
detail="Link a GitHub account with repo access before running user-authored cloud tasks.",
attr="pr_authorship_mode",
)
def _github_credential_source_extra_state(pr_authorship_mode, github_user_token: str | None) -> dict[str, str]:
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
GitHubCredentialSource,
PrAuthorshipMode,
)
if pr_authorship_mode != PrAuthorshipMode.USER:
return {}
source = GitHubCredentialSource.CALLER_TOKEN if github_user_token else GitHubCredentialSource.SERVER_INTEGRATION
return {"github_credential_source": source.value}
def _task_run_runtime_state_fields(validated_data: dict) -> dict[str, Any]:
return {
key: validated_data.get(key)
for key in (
"pr_authorship_mode",
"auto_publish",
"run_source",
"signal_report_id",
"runtime_adapter",
"model",
"reasoning_effort",
"context_window",
"fast_mode",
)
}
def bootstrap_task_run(
task_id: str | UUID, team_id: int, user_id: int | None, *, validated_data: dict
) -> contracts.TaskRunCreateResult | None:
"""Create a task run (without starting execution) from validated bootstrap data.
Returns ``None`` if the task isn't found/visible (the view raises 404). Otherwise returns a
``TaskRunCreateResult`` carrying either the created run DTO or a structured validation error.
Mirrors ``TaskRunViewSet.create`` byte-for-byte (minus the usage gate, which the view applies).
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
PrAuthorshipMode,
RunSource,
cache_github_user_token,
get_provider_for_runtime_adapter,
get_reasoning_effort_error,
)
task = _get_task_for_run_control(task_id, team_id, user_id)
if task is None:
return None
if task.origin_product == Task.OriginProduct.TASK_ANALYSIS:
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(
kind="detail", detail="An analysis task runs once. Start a new analysis instead."
)
)
if _is_unlinked_report_warm_task(task):
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(kind="detail", detail=REPORT_WARM_RUN_NOT_ACTIVATED)
)
mode = validated_data.get("mode", "background")
environment = validated_data.get("environment", TaskRun.Environment.LOCAL)
branch = validated_data.get("branch")
sandbox_environment_id = validated_data.get("sandbox_environment_id")
pr_authorship_mode = validated_data.get("pr_authorship_mode")
run_source = validated_data.get("run_source")
runtime_adapter = validated_data.get("runtime_adapter")
model = validated_data.get("model")
reasoning_effort = validated_data.get("reasoning_effort")
github_user_token = validated_data.get("github_user_token")
initial_permission_mode = validated_data.get("initial_permission_mode")
imported_mcp_servers = validated_data.get("imported_mcp_servers")
relayed_mcp_servers = validated_data.get("relayed_mcp_servers")
if run_source == RunSource.SIGNAL_REPORT:
pr_authorship_mode = PrAuthorshipMode.BOT
extra_state: dict | None = None
if initial_permission_mode is not None:
extra_state = {"initial_permission_mode": initial_permission_mode}
provider = get_provider_for_runtime_adapter(runtime_adapter)
for key, value in {
**_task_run_runtime_state_fields(validated_data),
"pr_base_branch": branch,
"pr_authorship_mode": pr_authorship_mode,
"provider": provider,
"rtk_enabled": validated_data.get("rtk_enabled"),
"benjamin_enabled": validated_data.get("benjamin_enabled"),
"claude_model_access": validated_data.get("claude_model_access"),
"codex_model_access": validated_data.get("codex_model_access"),
}.items():
if value is not None:
extra_state = extra_state or {}
extra_state[key] = value.value if hasattr(value, "value") else value
reasoning_effort_error = get_reasoning_effort_error(
runtime_adapter=runtime_adapter, model=model, reasoning_effort=reasoning_effort
)
if reasoning_effort_error is not None:
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(
kind="validation_error", code="invalid_input", detail=reasoning_effort_error, attr="reasoning_effort"
)
)
pr_authorship_mode, validation_error = _resolve_cloud_pr_authorship_mode(
task,
pr_authorship_mode=pr_authorship_mode,
request_user_id=user_id,
github_user_token=github_user_token,
)
if validation_error is not None:
return contracts.TaskRunCreateResult(error=validation_error)
if pr_authorship_mode is not None:
extra_state = extra_state or {}
extra_state["pr_authorship_mode"] = (
pr_authorship_mode.value if hasattr(pr_authorship_mode, "value") else pr_authorship_mode
)
if credential_source := _github_credential_source_extra_state(pr_authorship_mode, github_user_token):
extra_state = extra_state or {}
extra_state.update(credential_source)
custom_image_id = validated_data.get("custom_image_id")
if custom_image_id is not None:
custom_image = SandboxCustomImage.get_accessible_for_task(
image_id=custom_image_id, team_id=task.team_id, task_created_by_id=task.created_by_id
)
if custom_image is None:
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(kind="detail", detail="Invalid custom_image_id")
)
if not custom_image.is_ready:
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(
kind="detail", detail=f"Custom image is not ready (status: {custom_image.status})"
)
)
extra_state = extra_state or {}
extra_state["custom_image_id"] = str(custom_image.id)
if sandbox_environment_id is not None:
sandbox_environment = SandboxEnvironment.get_accessible_for_task(
environment_id=sandbox_environment_id,
team_id=task.team_id,
task_created_by_id=task.created_by_id,
)
if sandbox_environment is None:
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(kind="detail", detail="Invalid sandbox_environment_id")
)
extra_state = extra_state or {}
extra_state["sandbox_environment_id"] = str(sandbox_environment.id)
logger.info(
"Applying sandbox environment to task run",
extra={
"task_id": str(task.id),
"sandbox_environment_id": str(sandbox_environment.id),
"sandbox_environment_name": sandbox_environment.name,
"network_access_level": sandbox_environment.network_access_level,
},
)
logger.info(
"Creating task run for task %s with mode=%s, branch=%s, environment=%s", task.id, mode, branch, environment
)
try:
run = task.create_run(
environment=environment, mode=mode, branch=branch, extra_state=extra_state, acting_user_id=user_id
)
except InvalidModelAccess as error:
return contracts.TaskRunCreateResult(error=contracts.TaskRunValidationError(kind="detail", detail=str(error)))
except InvalidTaskOriginError as error:
return contracts.TaskRunCreateResult(
error=contracts.TaskRunValidationError(
kind="validation_error", code="invalid_input", detail=str(error), attr="origin_product"
)
)
except TaskOwnershipChangedError:
return None
if imported_mcp_servers or relayed_mcp_servers:
update_fields = ["updated_at"]
if imported_mcp_servers:
# Kept out of `state` (a plain JSONField) because header values carry credentials.
run.imported_mcp_servers = imported_mcp_servers
update_fields.append("imported_mcp_servers")
if relayed_mcp_servers:
run.relayed_mcp_servers = relayed_mcp_servers
update_fields.append("relayed_mcp_servers")
run.save(update_fields=update_fields)
if github_user_token and pr_authorship_mode == PrAuthorshipMode.USER:
cache_github_user_token(str(run.id), github_user_token)
return contracts.TaskRunCreateResult(run=_task_run_detail_to_dto(_task_run_queryset().get(pk=run.pk)))
WORKFLOW_START_FAILED_ERROR = "Failed to start task workflow."
def _trigger_task_processing_workflow(
task: Task,
run: TaskRun,
user_id: int | None,
*,
initial_message: str | None = None,
initial_artifact_ids: list[str] | None = None,
raise_on_error: bool = False,
) -> str | None:
from products.tasks.backend.logic.services.workflow_dispatch import ( # noqa: PLC0415
WorkflowDispatchOptions,
enqueue_or_start_workflow,
)
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
mcp_scopes_for_run_source,
parse_run_state,
)
from products.tasks.backend.temporal.process_task.workflow import PendingFollowup # noqa: PLC0415
# SIGNAL_REPORT: implementation runs log their work on the report (notes, code references)
# via the task:write artefact tools.
run_source = parse_run_state(run.state).run_source
posthog_mcp_scopes = mcp_scopes_for_run_source(run_source)
try:
logger.info("Attempting to trigger task processing workflow for task %s, run %s", task.id, run.id)
message = None
if initial_message or initial_artifact_ids:
message = PendingFollowup(
message=initial_message,
artifact_ids=initial_artifact_ids or [],
actor_user_id=user_id,
message_id=str(uuid4()),
)
enqueue_or_start_workflow(
run,
options=WorkflowDispatchOptions(
user_id=user_id,
posthog_mcp_scopes=posthog_mcp_scopes,
initial_message=message,
),
)
logger.info("Workflow trigger completed for task %s, run %s", task.id, run.id)
return None
except Exception as e:
logger.exception("Failed to trigger task processing workflow for task %s, run %s: %s", task.id, run.id, e)
if raise_on_error:
raise
return WORKFLOW_START_FAILED_ERROR
# Statuses from which a cloud run may be started via the start endpoint.
_STARTABLE_TASK_RUN_STATUSES = (TaskRun.Status.NOT_STARTED, TaskRun.Status.QUEUED)
def check_task_run_startable(run_id: str | UUID, task_id: str | UUID, team_id: int) -> tuple[str, str | None]:
"""Whether a run can be started via the start endpoint.
Returns ``"not_found"`` (run missing), ``"not_cloud"``, ``"scheduled"``,
``"bad_status:<current>"``, or ``"ok"``, together with the stored run source. The view
applies the usage gate before ``start_task_run``.
"""
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return "not_found", None
run_source = (run.state or {}).get("run_source")
if run.environment != TaskRun.Environment.CLOUD:
return "not_cloud", run_source
if run.status == TaskRun.Status.NOT_STARTED and run.scheduled_at is not None:
return "scheduled", run_source
if run.status not in _STARTABLE_TASK_RUN_STATUSES:
return f"bad_status:{run.status}", run_source
return "ok", run_source
def start_task_run(
run_id: str | UUID, task_id: str | UUID, team_id: int, user_id: int | None, *, validated_data: dict
) -> tuple[str, UUID | None]:
"""Apply run-scoped attachments and trigger the cloud workflow for a startable run.
Caller must have already verified startability and applied the usage gate. Returns
``(outcome, task_id)``: ``"not_found"``, ``"missing_artifacts:<csv>"``, or ``"started"``
(``task_id`` set). Rolls back any pending-state writes on failure (re-raising), mirroring
the original view.
"""
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_task_run_artifacts_by_id,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return "not_found", None
ensure_subscription_owner(run.state, user_id)
task = run.task
pending_user_message = validated_data.get("pending_user_message")
pending_user_artifact_ids = validated_data.get("pending_user_artifact_ids") or []
if pending_user_artifact_ids:
_, missing_artifact_ids = get_task_run_artifacts_by_id(run, pending_user_artifact_ids)
if missing_artifact_ids:
return "missing_artifacts:" + ",".join(missing_artifact_ids), None
state_updates: dict = {}
if task.runtime != Task.Runtime.PI:
if pending_user_message is not None:
state_updates["pending_user_message"] = pending_user_message
if pending_user_artifact_ids:
state_updates["pending_user_artifact_ids"] = pending_user_artifact_ids
previous_state = dict(run.state or {})
try:
with transaction.atomic():
task = Task.objects.select_for_update().get(id=task_id, team_id=team_id)
run = (
TaskRun.objects.select_for_update(of=("self",))
.select_related("task", "task__team", "task__created_by")
.get(id=run.id, task_id=task.id, team_id=team_id)
)
if not run.matches_task_ownership(task):
return "ownership_changed", None
if state_updates:
TaskRun.update_state_atomic(run.id, updates=state_updates)
run.refresh_from_db()
logger.info("Triggering workflow for task %s, existing run %s", task.id, run.id)
_trigger_task_processing_workflow(
task,
run,
user_id,
initial_message=(pending_user_message or task.description or None)
if task.runtime == Task.Runtime.PI
else None,
initial_artifact_ids=pending_user_artifact_ids if task.runtime == Task.Runtime.PI else None,
raise_on_error=True,
)
except Exception:
if state_updates:
rollback_updates = {
key: previous_state[key] for key in state_updates.keys() if key in previous_state
} or None
rollback_remove_keys = [key for key in state_updates.keys() if key not in previous_state] or None
TaskRun.update_state_atomic(run.id, updates=rollback_updates, remove_keys=rollback_remove_keys)
raise
return "started", task.id
def resume_task_run_in_cloud(
run_id: str | UUID, task_id: str | UUID, team_id: int, user_id: int | None
) -> tuple[str, contracts.TaskRunDetailDTO | None, str | None]:
"""Resume a run in a cloud sandbox, terminating any prior workflow.
Returns ``(outcome, run_dto, debug_use_modal)``. ``outcome`` is one of: ``"not_found"``,
``"already_active"`` (400), ``"not_cloud"`` (400), ``"ownership_changed"`` (400), ``"invalid_origin"`` (400),
``"auth_error:<detail>"``
(400, GitHub auth), ``"workflow_failed"`` (502), or ``"resumed"`` (run_dto set).
Mirrors ``TaskRunViewSet.resume_in_cloud``.
"""
from products.tasks.backend.facade.streams import reset_task_run_stream # noqa: PLC0415
from products.tasks.backend.redis import run_uses_dedicated_stream # noqa: PLC0415
from products.tasks.backend.temporal.client import ( # noqa: PLC0415 — keep temporalio off the api import path
resume_task_in_cloud_workflow,
)
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
PrAuthorshipMode,
get_pr_authorship_mode,
)
run = _get_visible_run(run_id, task_id, team_id)
if run is None:
return "not_found", None, None
ensure_subscription_owner(run.state, user_id)
from products.tasks.backend.logic.services.workflow_dispatch import ( # noqa: PLC0415
RestartSnapshot,
build_restart_payload,
create_dispatch,
)
from products.tasks.backend.models import TaskWorkflowDispatch # noqa: PLC0415
restart_dispatch_enabled = settings.TASKS_WORKFLOW_DISPATCH_OUTBOX_ENABLED
logger.info(
"resume_in_cloud_called",
extra={
"task_run_id": str(run.id),
"task_id": str(run.task_id),
"prior_status": run.status,
"prior_environment": run.environment,
"prior_state_keys": sorted((run.state or {}).keys()),
"prior_snapshot_external_id": (run.state or {}).get("snapshot_external_id"),
"prior_snapshot_kind": (run.state or {}).get("snapshot_kind"),
"prior_snapshot_mount_path": (run.state or {}).get("snapshot_mount_path"),
},
)
with transaction.atomic():
task = Task.objects.select_for_update().get(id=task_id, team_id=team_id)
run = (
TaskRun.objects.select_for_update(of=("self",))
.select_related("task", "task__created_by", "task__github_integration", "task__github_user_integration")
.get(pk=run.pk, task_id=task.id, team_id=team_id)
)
if not run.matches_task_ownership(task):
return "ownership_changed", None, None
if run.environment != TaskRun.Environment.CLOUD:
return "not_cloud", None, None
if task.origin_product not in Task.OriginProduct.values:
return "invalid_origin", None, None
is_cloud_active = run.status in (
TaskRun.Status.QUEUED,
TaskRun.Status.IN_PROGRESS,
)
if is_cloud_active:
return "already_active", None, None
if (
task.origin_product in {Task.OriginProduct.SIGNAL_REPORT, Task.OriginProduct.SIGNALS_SCOUT}
and (run.state or {}).get("billing_product") != "posthog_ai"
):
raise ValidationError("Start a new run to continue automated report or scout work.")
if get_pr_authorship_mode(run.task, run.state) == PrAuthorshipMode.USER:
pr_authorship_mode, validation_error = _resolve_cloud_pr_authorship_mode(
run.task,
pr_authorship_mode=PrAuthorshipMode.USER,
request_user_id=user_id,
github_user_token=None,
)
if validation_error is not None:
return f"auth_error:{validation_error.detail}", None, None
if pr_authorship_mode is not None:
run.state = {
**(run.state or {}),
"pr_authorship_mode": (
pr_authorship_mode.value if hasattr(pr_authorship_mode, "value") else pr_authorship_mode
),
}
prior_status = run.status
prior_environment = run.environment
prior_completed_at = run.completed_at
prior_queued_at = run.queued_at
prior_state = dict(run.state or {})
run.prepare_for_cloud_resume()
task.observe_run_started_beside_live_runs(run)
if restart_dispatch_enabled:
snapshot = RestartSnapshot(
status=prior_status,
environment=prior_environment,
completed_at=prior_completed_at.isoformat() if prior_completed_at else None,
queued_at=prior_queued_at.isoformat() if prior_queued_at else None,
state=prior_state,
)
create_dispatch(
run,
TaskWorkflowDispatch.Kind.RESTART,
build_restart_payload(user_id, snapshot),
run.workflow_id,
)
if restart_dispatch_enabled:
return "resumed", _task_run_detail_to_dto(_task_run_queryset().get(pk=run.pk)), None
logger.info("Resuming task run in cloud", extra={"task_run_id": str(run.id), "task_id": str(run.task_id)})
try:
if not reset_task_run_stream(
str(run.id),
use_dedicated=run_uses_dedicated_stream(run.state),
):
raise RuntimeError("Failed to reset task run event stream")
resume_task_in_cloud_workflow(str(run.id), run.workflow_id)
except Exception as e:
logger.exception("Failed to trigger resume workflow", extra={"task_run_id": str(run.id), "error": str(e)})
with transaction.atomic():
run = TaskRun.objects.select_for_update().get(pk=run.pk)
run.status = prior_status
run.environment = prior_environment
run.completed_at = prior_completed_at
run.queued_at = prior_queued_at
run.restore_cloud_resume_state(prior_state)
run.error_message = "Failed to start cloud workflow"
run.save(
update_fields=[
"status",
"environment",
"completed_at",
"queued_at",
"state",
"error_message",
"updated_at",
]
)
run.publish_stream_state_event()
return "workflow_failed", None, None
return "resumed", _task_run_detail_to_dto(run), None
# --- Task presentation CRUD + actions ---
# These back the thin ``TaskViewSet``. They mirror the original viewset's querysets
# (team scoping, ``task_visibility_q`` visibility, ordering, filters, annotations) and
# orchestration (title generation, signal-report linkage, workflow triggers, S3 artifact
# staging, presence beacons) byte-for-byte.
def signal_report_queryset():
"""The ``SignalReport`` manager queryset, for the task write serializer's report FK field.
Kept here so presentation never imports the ``signals`` product's models directly; team
scoping on the selected report is enforced by the serializer's ``validate_signal_report``.
"""
from products.signals.backend.models import ( # noqa: PLC0415 — cross-product import kept off the api import path
SignalReport,
)
return SignalReport.objects.all()
def channel_queryset():
"""Live ``Channel`` queryset for the task write serializer's channel FK field.
Kept here so presentation never imports tasks models directly. Deliberately
``unscoped()``: the serializer is also instantiated without team context (e.g.
drf-spectacular schema generation), where the fail-closed manager would raise.
Team scoping comes from the serializer's team-scoped field, ownership of
personal channels from ``validate_channel``.
"""
return Channel.objects.unscoped().filter(deleted=False)
def is_internal_debug_team(team_id: int | None) -> bool:
"""Whether the team is the PostHog-internal debugging team. Mirrors the original view helper."""
from django.conf import settings # noqa: PLC0415
if settings.DEBUG and not settings.TEST:
return team_id == 1
return team_id == 2 and settings.CLOUD_DEPLOYMENT == "US"
def _task_detail_queryset():
return Task.objects.select_related(
"created_by", "team", "github_integration", "github_user_integration"
).prefetch_related("runs")
def _visible_task_qs(
team_id: int,
user_id: int | None,
*,
bypass_visibility: bool = False,
for_control: bool = False,
for_list: bool = False,
):
"""Team-scoped live tasks, gated by read visibility — or by the narrower
control predicate when ``for_control`` (mutations, runs, agent commands).
The read branch ORs in ``_shared_slack_thread_q()`` so a task shared in a Slack channel
is readable team-wide, matching ``task_accessible_for_run_view``. Without it the run
endpoint admits a channel collaborator while task detail returns 404 for the same task.
"""
qs = Task.objects.filter(team_id=team_id, deleted=False).filter(scout_trial_visibility_q(user_id))
if not bypass_visibility:
channel_team_id = team_id if for_list else None
qs = qs.filter(
task_control_q(user_id, channel_team_id)
if for_control
else task_visibility_q(user_id, channel_team_id) | _shared_slack_thread_q()
)
# Another product may hide tasks it owns from this user, for example the copies of chats a
# user cannot continue as tasks yet.
hidden = hidden_task_ids(team_id, user_id)
if hidden:
qs = qs.exclude(id__in=hidden)
return qs
def task_review(team_id: int, task_id: str, user_id: int, page: int) -> dict:
from products.tasks.backend.logic.task_review import ( # noqa: PLC0415 — keep GitHub integration deps off the api import path
task_review as build_task_review,
)
return build_task_review(team_id, task_id, user_id, page)
def get_pull_request_titles(team_id: int, user_id: int, task_ids: list[UUID]) -> dict[str, str]:
from products.tasks.backend.logic.pull_request_titles import ( # noqa: PLC0415 — keep GitHub integration deps off the api import path
pull_request_titles,
)
return pull_request_titles(team_id, user_id, task_ids)
def get_task_detail(
task_id: str | UUID,
team_id: int,
user_id: int | None,
*,
bypass_visibility: bool = False,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> contracts.TaskDetailDTO | None:
"""A single task as a detail DTO, team-scoped and visibility-gated.
``bypass_visibility`` mirrors the ``?ph_debug=true`` retrieve path for internal-debug teams.
"""
task = (
_visible_task_qs(team_id, user_id, bypass_visibility=bypass_visibility)
.select_related("created_by")
.prefetch_related("runs", Prefetch("team", queryset=Team.objects.only("id", "name")))
.filter(id=task_id)
.first()
)
return (
_task_detail_to_dto(task, user_id=user_id, analytics_context_reader=analytics_context_reader)
if task is not None
else None
)
def get_conversation_task_dtos(
task_ids: Sequence[str | UUID], team_id: int, user_id: int | None
) -> dict[UUID, contracts.TaskDetailDTO]:
"""Visible task payloads for the Max conversation API, keyed by task id.
``latest_run`` stays excluded so conversation lists never presign per-row log URLs. A single
``latest_run_id`` subquery carries the id that the frontend needs to reconnect to sandbox logs.
"""
if not task_ids:
return {}
latest_run_id_sq = (
TaskRun.objects.filter(task=OuterRef("pk"), team_id=team_id).order_by("-created_at", "-id").values("id")[:1]
)
tasks = (
Task.objects.filter(team_id=team_id, id__in=task_ids, deleted=False)
.filter(task_visibility_q(user_id, team_id))
.select_related("created_by")
.prefetch_related(Prefetch("team", queryset=Team.objects.only("id", "name")))
.annotate(_latest_run_id=Subquery(latest_run_id_sq))
)
return {task.id: _task_detail_to_dto(task, user_id=user_id, include_latest_run=False) for task in tasks}
def task_analysis_enabled(team: Team, user: User) -> bool:
"""Rollout gate for the PostHog-funded analysis endpoint, fail-closed like the Pi gates."""
distinct_id = user.distinct_id or f"user_{user.id}"
organization_id = str(team.organization_id)
try:
return bool(
posthoganalytics.feature_enabled(
TASK_ANALYSIS_FEATURE_FLAG,
distinct_id,
groups={"organization": organization_id},
group_properties={"organization": {"id": organization_id}},
only_evaluate_locally=False,
send_feature_flag_events=False,
)
)
except Exception:
logger.exception("task-analysis flag check failed; treating as disabled")
return False
def task_runtime(task_id: str | UUID, team_id: int, user_id: int | None, *, for_control: bool = False) -> str | None:
return (
_visible_task_qs(team_id, user_id, for_control=for_control)
.filter(id=task_id)
.values_list("runtime", flat=True)
.first()
)
@frozen
class ControlVisibleTask:
runtime: str
origin_product: str
def task_control_runtime_and_origin(
task_id: str | UUID, team_id: int, user_id: int | None
) -> ControlVisibleTask | None:
"""The runtime and origin product of a task the user may drive, or ``None`` when it is not
control-visible.
One narrow control-predicate query for the warm-resume gate. The control predicate is a subset
of the read predicate, so a control-visible task is always read-visible. This covers the same
404 gate as a read query plus a separate control ``EXISTS`` check. It does not load the detail
DTO, prefetch every run, or presign the latest run's log URL.
"""
row = (
_visible_task_qs(team_id, user_id, for_control=True)
.filter(id=task_id)
.values_list("runtime", "origin_product")
.first()
)
if row is None:
return None
runtime, origin_product = row
return ControlVisibleTask(runtime=runtime, origin_product=origin_product)
def task_visible(task_id: str | UUID, team_id: int, user_id: int | None, *, for_control: bool = False) -> bool:
"""Whether a non-deleted task exists for the team and is visible to the user.
Mirrors the existence gate ``TaskViewSet.get_object()`` applied (team + ``deleted=False`` +
``task_visibility_q``). Used by the ``run`` action to 404 before the usage gate, preserving
the original ordering; the ``run`` action passes ``for_control`` since starting a run drives
the task.
"""
visible = _visible_task_qs(team_id, user_id, for_control=for_control).filter(id=task_id)
if not for_control:
return visible.exists()
row = visible.values_list("profile", "created_by_id").first()
if row is None:
return False
profile_key, created_by_id = row
return drive_allowed(profile_key, created_by_id=created_by_id, user_id=user_id)
def _task_drive_allowed(task: Task, user_id: int | None) -> bool:
return drive_allowed(task.profile, created_by_id=task.created_by_id, user_id=user_id)
def scout_trial_task_ids(team_id: int, *, visible_task_id: UUID | None = None) -> Iterable[UUID]:
tasks = Task.objects.filter(Task.scout_experiment_q(), team_id=team_id)
if visible_task_id is not None:
tasks = tasks.exclude(id=visible_task_id)
return tasks.values_list("id", flat=True)
def is_scout_trial_task(task_id: str | UUID, team_id: int) -> bool:
return Task.objects.filter(Task.scout_experiment_q(), id=task_id, team_id=team_id).exists()
def list_pinned_task_ids(team_id: int, user_id: int, *, exclude_task_ids: Iterable[UUID] = ()) -> list[UUID]:
visible_tasks = _visible_task_qs(team_id, user_id, for_list=True).exclude(id__in=exclude_task_ids).values("id")
return list(
TaskPin.objects.filter(user_id=user_id, task_id__in=Subquery(visible_tasks))
.order_by("-pinned_at")
.values_list("task_id", flat=True)
)
def set_task_pinned(task_id: str | UUID, team_id: int, user_id: int, *, pinned: bool) -> bool | None:
if not task_visible(task_id, team_id, user_id):
return None
if pinned:
TaskPin.objects.get_or_create(user_id=user_id, task_id=task_id)
else:
TaskPin.objects.filter(user_id=user_id, task_id=task_id).delete()
return pinned
async def select_repository_for_message(team_id: int, user_id: int, message: str, *, origin_product: str) -> str | None:
"""Pick the repository a free-form chat message is most likely about.
Kept as a lazy facade wrapper so API importers do not load the repo-selection agent or
sandbox/Temporal dependencies on their request import path.
"""
from products.tasks.backend.logic.repo_selection.cascade import ( # noqa: PLC0415 — keeps repo-selection agent imports lazy
select_repository_for_message as select_repository_for_message_impl,
)
return await select_repository_for_message_impl(
team_id, user_id, message, origin_product=Task.OriginProduct(origin_product)
)
def list_workflow_last_runs(
team_id: int, user_id: int | None, hog_flow_ids: Iterable[UUID]
) -> dict[UUID, contracts.WorkflowLastRunDTO]:
"""The newest visible task of each given workflow, keyed by workflow id, in one query.
Uses the same rows as the workflow's run history (``hog_flow_id`` task list with archived tasks
included), so a list row never names a run that the history hides. Workflows without a
visible task are absent from the result.
"""
ids = list(hog_flow_ids)
if not ids:
return {}
latest_run = TaskRun.objects.filter(task=OuterRef("pk"), team_id=team_id).order_by("-created_at", "-id")
rows = (
_visible_task_qs(team_id, user_id, for_list=True)
.filter(source_q(SourceKind.HOG_FLOW, ids), internal=False)
.annotate(
_workflow_id=Case(
When(
source_kind=SourceKind.HOG_FLOW.value,
source_id__isnull=False,
then=Cast("source_id", UUIDField()),
),
default=F("hog_flow_id"),
output_field=UUIDField(),
),
)
.order_by("_workflow_id", "-created_at", "-id")
.distinct("_workflow_id")
.annotate(
_run_status=Subquery(latest_run.values("status")[:1]),
_run_created_at=Subquery(latest_run.values("created_at")[:1]),
)
.values_list("_workflow_id", "id", "created_at", "_run_status", "_run_created_at")
)
return {
hog_flow_id: contracts.WorkflowLastRunDTO(
hog_flow_id=hog_flow_id,
task_id=task_id,
status=run_status or TaskRun.Status.NOT_STARTED,
ran_at=run_created_at or created_at,
)
for hog_flow_id, task_id, created_at, run_status, run_created_at in rows
}
#: Orderings the task list accepts, keyed by the value clients send. Both fall back to `-id` so a
#: page boundary can't drop or repeat a row when two tasks share a timestamp. A null
#: `last_activity_at` (rows written outside the ORM) sorts first under `DESC`, which is where a row
#: with no known activity belongs.
TASK_LIST_ORDERINGS: dict[str, tuple[str, ...]] = {
"-last_activity_at": ("-last_activity_at", "-id"),
"-created_at": ("-created_at", "-id"),
}
DEFAULT_TASK_LIST_ORDERING = "-created_at"
#: Built from the two source classes, so a new origin product becomes a source without an edit here.
#: Product-private origin products are left out because the task list never shows their tasks.
# django-stubs types only the class-body form of TextChoices; Django supports this functional form.
TaskListSource = TextChoices( # type: ignore[call-overload]
"TaskListSource",
[
# The value is also the label, so the API docs show "posthog_ai", not a title-cased "Posthog Ai".
(source.upper(), (source, source))
for source in sorted(
{
*TaskClientProvenance.values,
*(
product
for product in Task.OriginProduct.values
if product != Task.OriginProduct.USER_CREATED and product not in PRODUCT_PRIVATE_ORIGIN_PRODUCTS
),
}
)
],
)
def _task_sources_q(sources: list[str]) -> Q:
user_created = Q(origin_product=Task.OriginProduct.USER_CREATED)
matches = Q(pk__in=[])
for source in sources:
if source == TaskClientProvenance.POSTHOG_DESKTOP:
# A user-created task with no other known client counts as desktop, the same as the desktop app.
matches |= user_created & ~Q(
client_provenance__in=[TaskClientProvenance.POSTHOG_MOBILE, TaskClientProvenance.POSTHOG_WEB]
)
elif source == TaskClientProvenance.POSTHOG_WEB:
# PostHog AI runs in the web app, so the desktop app shows its tasks as web tasks too.
matches |= (user_created & Q(client_provenance=source)) | Q(origin_product=Task.OriginProduct.POSTHOG_AI)
elif source in TaskClientProvenance.values:
matches |= user_created & Q(client_provenance=source)
else:
matches |= Q(origin_product=source)
return matches
def _task_source(origin_product: str, client_provenance: str | None) -> str:
# The reverse of _task_sources_q, so every listed source filters back to its own tasks.
if origin_product == Task.OriginProduct.POSTHOG_AI:
return TaskClientProvenance.POSTHOG_WEB
if origin_product == Task.OriginProduct.USER_CREATED:
if client_provenance in (TaskClientProvenance.POSTHOG_MOBILE, TaskClientProvenance.POSTHOG_WEB):
return client_provenance
return TaskClientProvenance.POSTHOG_DESKTOP
return origin_product
def list_task_sources(team_id: int, user_id: int, *, exclude_task_ids: Iterable[UUID] = ()) -> list[str]:
"""Distinct task list sources of the user's own visible, non-archived, non-internal tasks."""
pairs = (
_visible_task_qs(team_id, user_id, for_list=True)
.filter(internal=False, archived=False, created_by_id=user_id)
.exclude(id__in=exclude_task_ids)
.order_by()
.values_list("origin_product", "client_provenance")
.distinct()
)
return sorted({_task_source(origin_product, client_provenance) for origin_product, client_provenance in pairs})
def _list_tasks_queryset(
team_id: int, user_id: int | None, *, filters: dict, bypass_visibility: bool = False
) -> QuerySet[Task]:
latest_run = TaskRun.objects.filter(task=OuterRef("pk"), team_id=team_id).order_by("-created_at", "-id")
ordering = TASK_LIST_ORDERINGS.get(filters.get("ordering") or "", TASK_LIST_ORDERINGS[DEFAULT_TASK_LIST_ORDERING])
qs = _visible_task_qs(team_id, user_id, bypass_visibility=bypass_visibility, for_list=True).order_by(*ordering)
origin_product = filters.get("origin_product")
if origin_product:
qs = qs.filter(origin_product=origin_product)
client_provenance = filters.get("client_provenance")
if client_provenance:
qs = qs.filter(client_provenance=client_provenance)
exclude_origin_product = filters.get("exclude_origin_product")
if exclude_origin_product:
qs = qs.exclude(origin_product=exclude_origin_product)
sources = filters.get("sources")
if sources:
qs = qs.filter(_task_sources_q(sources))
stage = filters.get("stage")
if stage:
stage_run = TaskRun.objects.filter(task=OuterRef("pk"), team_id=team_id, stage=stage)
qs = qs.filter(Exists(stage_run))
organization = filters.get("organization")
repository = filters.get("repository")
created_by = filters.get("created_by")
search = filters.get("search")
status_filter = filters.get("status")
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}")
if organization:
org_str = organization.strip().lower()
qs = qs.filter(repository__istartswith=f"{org_str}/")
if created_by:
qs = qs.filter(created_by_id=created_by)
channel = filters.get("channel")
if channel:
qs = qs.filter(channel_id=channel)
hog_flow_id = filters.get("hog_flow_id")
if hog_flow_id:
qs = qs.filter(source_q(SourceKind.HOG_FLOW, [hog_flow_id]))
if search:
search_term = search.strip()
if search_term:
search_q = Q(title__icontains=search_term) | Q(description__icontains=search_term)
number_part = search_term.split("-")[-1].strip()
if number_part.isdigit():
search_q |= Q(task_number=int(number_part))
qs = qs.filter(search_q)
if status_filter:
latest_run_status = latest_run.values("status")[:1]
qs = qs.annotate(_latest_run_status=Subquery(latest_run_status)).filter(_latest_run_status=status_filter)
# PR/CI state filters read the snapshot the PR webhook and the CI follow-up
# loop persist onto a run's output. KeyTextTransform, so the comparison is
# text = text.
pr_state = filters.get("pr_state")
if pr_state:
# Anchored on the newest PR-carrying run, the one `_task_detail_to_dto` inherits
# `latest_run.output` from. A resumed run never gains a `pr_state` of its own, so reading
# the newest run would answer `pr_state=open` differently from the `latest_run` this same
# endpoint returns.
latest_pr_run = latest_run.filter(_PR_CARRYING_OUTPUT_Q)
latest_run_pr_state = latest_pr_run.annotate(_pr_state=KeyTextTransform("pr_state", "output")).values(
"_pr_state"
)[:1]
qs = qs.annotate(_latest_run_pr_state=Subquery(latest_run_pr_state))
if pr_state == "merged":
# Runs merged before pr_state existed only carry the older
# pr_merged flag; honor both spellings.
latest_run_pr_merged = latest_pr_run.annotate(_pr_merged=KeyTextTransform("pr_merged", "output")).values(
"_pr_merged"
)[:1]
qs = qs.annotate(_latest_run_pr_merged=Subquery(latest_run_pr_merged)).filter(
Q(_latest_run_pr_state="merged") | Q(_latest_run_pr_merged="true")
)
else:
qs = qs.filter(_latest_run_pr_state=pr_state)
# `ci_status` stays on the newest run: unlike the PR, it is not inherited across a resume.
ci_status = filters.get("ci_status")
if ci_status:
latest_run_ci_status = latest_run.annotate(_ci_status=KeyTextTransform("ci_status", "output")).values(
"_ci_status"
)[:1]
qs = qs.annotate(_latest_run_ci_status=Subquery(latest_run_ci_status)).filter(_latest_run_ci_status=ci_status)
# Pins are per-user, so "pinned" means the requesting user's pins — and
# without a user (service callers) nothing is pinned.
if str(filters.get("pinned")).lower() == "true":
if user_id is None:
qs = qs.none()
else:
qs = qs.filter(Exists(TaskPin.objects.filter(task=OuterRef("pk"), user_id=user_id)))
commented_by = filters.get("commented_by")
if commented_by:
qs = qs.filter(
Exists(
TaskThreadMessage.objects.for_team(team_id).filter(
task=OuterRef("pk"),
author_id=commented_by,
author_kind=TaskThreadMessage.AuthorKind.HUMAN,
)
)
)
mentions = filters.get("mentions")
if mentions:
qs = qs.filter(
Exists(
TaskThreadMessageMention.objects.for_team(team_id)
.filter(task=OuterRef("pk"), mentioned_user_id=mentions)
# Same rule as list_mentions: legacy turn_complete rows are hidden
# from threads, so their indexed mentions must not match either.
.exclude(message__event="turn_complete")
)
)
# `internal` controls default visibility, not access — task visibility (applied above) is the real
# authorization boundary, open to any team member. `all` returns both, `true` returns only-internal,
# and the default excludes internal tasks so the main task list stays clean.
internal_param = filters.get("internal")
if internal_param == "all":
pass
elif internal_param == "true":
qs = qs.filter(internal=True)
else:
qs = qs.filter(internal=False)
archived_param = filters.get("archived")
if archived_param == "true":
qs = qs.filter(archived=True)
elif archived_param == "all":
pass
else:
qs = qs.filter(archived=False)
# The list DTO needs only two relations: ``created_by`` for ``_user_basic_info`` and
# ``team.name`` for the ``slug`` prefix (the integration FK ids are columns on the task row).
# Narrow prefetches keep the full ~100-column Team row and the full User row out of every
# task row. Latest runs are resolved per page in ``_tasks_to_dtos``, which avoids a
# correlated ``posthog_task_run`` subquery on every task row.
qs = qs.prefetch_related(
Prefetch("created_by", queryset=User.objects.only(*_TASK_CREATED_BY_FIELDS)),
Prefetch("team", queryset=Team.objects.only("id", "name")),
)
return qs
def _latest_runs_by_task_id(task_ids: Iterable[UUID], team_id: int) -> dict[UUID, TaskRun]:
task_id_list = list(task_ids)
if not task_id_list:
return {}
runs = (
TaskRun.objects.filter(team_id=team_id, task_id__in=task_id_list)
.order_by("task_id", "-created_at", "-id")
.distinct("task_id")
)
return {run.task_id: run for run in runs}
def _tasks_to_dtos(
tasks: Iterable[Task],
team_id: int,
user_id: int | None = None,
*,
analytics_context_reader: Callable[[object], bool] | None = None,
) -> list[contracts.TaskDetailDTO]:
task_list = list(tasks)
latest_runs_by_task_id = _latest_runs_by_task_id((task.id for task in task_list), team_id)
# Resolved for the whole page in one query, rather than one per task inside the mapper.
needs_prior_pr = [
task.id
for task in task_list
if (run := latest_runs_by_task_id.get(task.id)) is not None and not read_pr_urls(run.output)
]
prior_pr_output_by_task_id = get_prior_pr_output_by_task(team_id, needs_prior_pr)
return [
_task_detail_to_dto(
task,
user_id=user_id,
latest_run=latest_runs_by_task_id.get(task.id),
prior_pr_output=prior_pr_output_by_task_id.get(str(task.id)),
analytics_context_reader=analytics_context_reader,
)
for task in task_list
]
def list_tasks(team_id: int, user_id: int | None, *, filters: dict) -> list[contracts.TaskDetailDTO]:
"""All visible tasks for the team as DTOs, mirroring the task list view filters."""
return _tasks_to_dtos(_list_tasks_queryset(team_id, user_id, filters=filters), team_id, user_id)
_SEARCH_KIND_ORDER = (
TaskSearchDocument.Kind.TASK,
TaskSearchDocument.Kind.CANVAS,
TaskSearchDocument.Kind.CHANNEL,
TaskSearchDocument.Kind.PULL_REQUEST,
TaskSearchDocument.Kind.ARTIFACT,
)
_SEARCH_BULK_KINDS = {TaskSearchDocument.Kind.PULL_REQUEST, TaskSearchDocument.Kind.ARTIFACT}
_SEARCH_BULK_KIND_PAGE_SHARE = 0.25
_SEARCH_CANDIDATE_FACTOR = 3
_SEARCH_MAX_CANDIDATES = 150
def _mixed_search_page(documents: Iterable[TaskSearchDocument], page_size: int) -> list[TaskSearchDocument]:
quota = int(page_size * _SEARCH_BULK_KIND_PAGE_SHARE)
used: Counter[str] = Counter()
page: list[TaskSearchDocument] = []
overflow: list[TaskSearchDocument] = []
for document in documents:
if document.kind in _SEARCH_BULK_KINDS and used[document.kind] >= quota:
overflow.append(document)
continue
used[document.kind] += 1
page.append(document)
return (page + overflow)[:page_size]
def _search_latest_run_summary(run: TaskRun | None) -> contracts.TaskLatestRunSummaryDTO | None:
"""The run state a search row needs to draw the task's icon."""
if run is None:
return None
interactive = (run.state or {}).get("mode") == "interactive"
output = run.output if isinstance(run.output, dict) else {}
pr_url = output.get("pr_url")
pr_url = pr_url if isinstance(pr_url, str) and pr_url else None
return contracts.TaskLatestRunSummaryDTO(
id=run.id,
status=run.status,
environment=run.environment,
mode="interactive" if interactive else "background",
pr_url=pr_url,
pr_state=_pull_request_state(output) if pr_url else None,
)
def _search_result_payload(document: TaskSearchDocument, latest_runs: dict[Any, TaskRun]) -> dict:
"""One search row, with the fields a client needs to draw it without a second request."""
task = document.task if document.task_id else None
return {
"id": str(document.id),
"kind": document.kind,
"title": document.title,
"subtitle": document.subtitle,
"task_id": str(document.task_id) if document.task_id else None,
"task_run_id": str(document.task_run_id) if document.task_run_id else None,
"channel_id": str(document.channel_id) if document.channel_id else None,
"created_by": _user_basic_info(task.created_by if task else None),
"origin_product": task.origin_product if task else None,
"latest_run": _search_latest_run_summary(latest_runs.get(document.task_id) if document.task_id else None),
"updated_at": document.updated_at,
"metadata": document.metadata,
}
def search_tasks(
team_id: int,
user_id: int | None,
query: str,
*,
limit: int = 20,
bypass_visibility: bool = False,
exclude_task_ids: Iterable[UUID] = (),
) -> list[dict]:
normalized = query.strip().lower()
if not normalized:
return []
visible_task_ids = (
_visible_task_qs(team_id, user_id, bypass_visibility=bypass_visibility, for_list=True)
.filter(internal=False)
.exclude(id__in=exclude_task_ids)
.values("id")
)
visibility = Q(task_id__in=Subquery(visible_task_ids)) | (
Q(task__isnull=True, channel__deleted=False) & Channel.visible_to_q(user_id, relation="channel")
)
identifiers = [normalized]
pr_match = re.match(r"^https?://github\.com/([^/]+/[^/]+)/pull/(\d+)(?:[/?#].*)?$", normalized)
if pr_match:
repository, number = pr_match.groups()
identifiers.extend(
[f"https://github.com/{repository}/pull/{number}", f"{repository}#{number}", f"#{number}", number]
)
exact_match = Q()
for identifier in identifiers:
exact_match |= Q(exact_identifiers__contains=[identifier])
matches = exact_match
if len(normalized) >= 3:
matches |= Q(search_text__icontains=normalized)
page_size = min(limit, 50)
candidates = (
TaskSearchDocument.objects.for_team(team_id)
.select_related("task__created_by")
.filter(visibility)
.filter(matches)
.annotate(
_rank=Case(
When(exact_match, then=Value(0)),
When(search_text__startswith=normalized, then=Value(1)),
default=Value(2),
output_field=IntegerField(),
),
_kind_rank=Case(
*[When(kind=kind, then=Value(rank)) for rank, kind in enumerate(_SEARCH_KIND_ORDER)],
default=Value(len(_SEARCH_KIND_ORDER)),
output_field=IntegerField(),
),
)
.order_by("_rank", "_kind_rank", "-updated_at")[
: min(page_size * _SEARCH_CANDIDATE_FACTOR, _SEARCH_MAX_CANDIDATES)
]
)
documents = _mixed_search_page(candidates, page_size)
latest_runs = _latest_runs_by_task_id((document.task_id for document in documents if document.task_id), team_id)
return [_search_result_payload(document, latest_runs) for document in documents]
def inaccessible_repositories_via_integration(team_id: int, integration_id: int, repositories: list[str]) -> list[str]:
return _inaccessible_repositories_via_integration(team_id, integration_id, repositories)
def list_task_repositories(team_id: int, user_id: int | None, *, exclude_task_ids: Iterable[UUID] = ()) -> list[str]:
"""Distinct repositories used by non-deleted, non-internal visible tasks for the team."""
tasks = (
Task.objects.filter(team_id=team_id, deleted=False, internal=False)
.filter(task_visibility_q(user_id, team_id))
.exclude(id__in=exclude_task_ids)
)
plural = (
tasks.exclude(repositories=[])
.annotate(repository_name=Func(F("repositories"), function="unnest", output_field=CharField()))
.values_list("repository_name", flat=True)
.distinct()
)
legacy = (
tasks.filter(repositories=[])
.exclude(repository__isnull=True)
.exclude(repository="")
.values_list("repository", flat=True)
.distinct()
)
return sorted(set(plural) | {repository for repository in legacy if repository})
def _latest_run_summary(
raw: object, prior_pr: object = None, *, can_read_summary: bool
) -> contracts.TaskLatestRunSummaryDTO | None:
if not isinstance(raw, dict):
return None
# Same inheritance the task detail response applies: a run that opened no PR of its own shows
# the one an earlier run opened, so the sidebar and the detail view agree about a resumed task.
pr_source = raw if read_pr_urls(raw) else (prior_pr if isinstance(prior_pr, dict) else {})
urls = read_pr_urls(pr_source)
pr_url = urls[0] if urls else None
return contracts.TaskLatestRunSummaryDTO(
id=raw["id"],
status=raw.get("status"),
environment=raw.get("environment"),
mode=raw.get("mode", "background"),
pr_url=pr_url,
pr_state=_pull_request_state(pr_source) if pr_url else None,
task_summary=(raw.get("task_summary") or raw.get("prior_run_summary")) if can_read_summary else None,
)
def get_task_summaries(
team_id: int,
user_id: int | None,
*,
ids: list,
limit: int | None = None,
offset: int = 0,
exclude_task_ids: Iterable[UUID] = (),
analytics_context_reader: Callable[[object], bool] | None = None,
) -> tuple[list[contracts.TaskSummaryDTO], int]:
"""Summary fields for the requested tasks, mirroring ``TaskViewSet.summaries``."""
from django.db.models.functions import JSONObject # noqa: PLC0415
latest_run = (
TaskRun.objects.filter(task=OuterRef("pk"), team_id=team_id)
.order_by("-created_at", "-id")
.annotate(
_mode=Case(
When(state__mode="interactive", then=Value("interactive")),
default=Value("background"),
output_field=CharField(),
),
_data=JSONObject(
id="id",
status="status",
environment="environment",
mode="_mode",
pr_url=KeyTransform("pr_url", "output"),
pr_urls=KeyTransform("pr_urls", "output"),
pr_state=KeyTransform("pr_state", "output"),
pr_merged=KeyTransform("pr_merged", "output"),
task_summary="state__task_summary",
prior_run_summary="state__prior_run_summary",
has_analytics_context=Case(
When(state__has_key="analytics_query_context", then=Value(True)),
default=Value(False),
output_field=BooleanField(),
),
analytics_query_context="state__analytics_query_context",
),
)
)
# The newest run that opened a PR, which is not always the newest run.
latest_pr_run = (
TaskRun.objects.filter(task=OuterRef("pk"), team_id=team_id)
.filter(_PR_CARRYING_OUTPUT_Q)
.order_by("-created_at", "-id")
.annotate(
_pr=JSONObject(
pr_url=KeyTransform("pr_url", "output"),
pr_urls=KeyTransform("pr_urls", "output"),
pr_state=KeyTransform("pr_state", "output"),
pr_merged=KeyTransform("pr_merged", "output"),
)
)
)
tasks = (
Task.objects.filter(team_id=team_id, deleted=False, id__in=ids)
.filter(task_visibility_q(user_id, team_id))
.exclude(id__in=exclude_task_ids)
.annotate(
_latest_run=Subquery(latest_run.values("_data")[:1]),
_latest_pr_run=Subquery(latest_pr_run.values("_pr")[:1]),
)
.order_by("-created_at", "id")
)
count = tasks.count()
if limit is not None:
tasks = tasks[offset : offset + limit]
summaries: list[contracts.TaskSummaryDTO] = []
for task in tasks:
raw = getattr(task, "_latest_run", None)
can_read_summary = task.origin_product != Task.OriginProduct.WORKFLOW or (
user_id is not None and task.created_by_id == user_id
)
if isinstance(raw, dict) and raw.get("has_analytics_context"):
can_read_summary = (
can_read_summary
and analytics_context_reader is not None
and analytics_context_reader(raw.get("analytics_query_context"))
)
latest = _latest_run_summary(raw, getattr(task, "_latest_pr_run", None), can_read_summary=can_read_summary)
summaries.append(
contracts.TaskSummaryDTO(
id=task.id,
title=task.title,
repository=task.repository,
created_by_id=task.created_by_id,
created_at=task.created_at,
updated_at=task.updated_at,
origin_product=task.origin_product,
latest_run=latest,
)
)
return summaries, count
def compute_repository_readiness(team_id: int, *, repository: str, window_days: int, refresh: bool) -> dict:
"""Autonomy-readiness details for a repository. Thin wrapper over the internal computation."""
from posthog.models import Team # noqa: PLC0415
from products.tasks.backend.repository_readiness import ( # noqa: PLC0415 — keep readiness deps off the api import path
compute_repository_readiness as _compute,
)
team = Team.objects.get(id=team_id)
return _compute(team=team, repository=repository, window_days=window_days, refresh=refresh)
def _capture_no_repo_selection_override(
*, team: Team, report_id: str, resolved_repository: str | None, relationship: str | None
) -> None:
"""Record a person starting work on a report whose scout chose no repository.
The count tells the signals team how often the scouts' `NO_REPO` default disagrees with what a
person wanted, and `resolved_repository` separates a recovery from a cascade that also found
nothing. `relationship` separates a "Create PR" override from an Ask AI one, which start from
different intents. Keyed on the team, like the other scout events. Best-effort: a capture
failure must never fail the task creation."""
try:
posthoganalytics.capture(
distinct_id=str(team.uuid),
event="signal_report_no_repo_selection_overridden",
properties={
"report_id": report_id,
"team_id": team.id,
"resolved_repository": resolved_repository,
"relationship": relationship,
},
groups=groups(team=team),
)
except Exception as e:
logger.warning("signal_report_no_repo_selection_overridden capture failed for report %s: %s", report_id, e)
def _capture_report_task_refused_without_repository(*, team: Team, report_id: str) -> None:
try:
posthoganalytics.capture(
distinct_id=str(team.uuid),
event="signal_report_implementation_refused_no_repository",
properties={"report_id": report_id, "team_id": team.id},
groups=groups(team=team),
)
except Exception as e:
logger.warning(
"signal_report_implementation_refused_no_repository capture failed for report %s: %s", report_id, e
)
def create_task_and_run(
team_id: int,
user_id: int | None,
*,
validated_data: dict,
run_data: dict,
client_provenance: TaskClientProvenance | None = None,
code_access_allowed: bool = False,
) -> contracts.TaskRunResult:
from products.signals.backend.facade.api import ReportTaskCapExceeded
if custom_image_id := run_data.get("custom_image_id"):
custom_image = SandboxCustomImage.get_accessible_for_task(
image_id=custom_image_id, team_id=team_id, task_created_by_id=user_id
)
if custom_image is None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail="Invalid custom_image_id")
)
if not custom_image.is_ready:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="detail", detail=f"Custom image is not ready (status: {custom_image.status})"
)
)
if sandbox_environment_id := run_data.get("sandbox_environment_id"):
sandbox_environment = SandboxEnvironment.get_accessible_for_task(
environment_id=sandbox_environment_id, team_id=team_id, task_created_by_id=user_id
)
if sandbox_environment is None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail="Invalid sandbox_environment_id")
)
create_data = dict(validated_data)
create_data.pop("branch", None)
task = create_task(
team_id,
user_id,
validated_data=create_data,
client_provenance=client_provenance,
code_access_allowed=code_access_allowed,
)
try:
result = run_task(task.id, team_id, user_id, validated_data=run_data)
if result is None:
return contracts.TaskRunResult(task=task, run_error="Failed to create task run.")
return contracts.TaskRunResult(
task=result.task or task,
run_error=result.error.detail if result.error else result.run_error,
)
except ReportTaskCapExceeded as error:
return contracts.TaskRunResult(task=task, run_error=error.detail)
except Exception:
logger.exception("Failed to create first run for task %s", task.id)
return contracts.TaskRunResult(task=task, run_error="Failed to create task run.")
def create_task(
team_id: int,
user_id: int | None,
*,
validated_data: dict,
client_provenance: TaskClientProvenance | None = None,
code_access_allowed: bool = False,
warm_retry_token: str | None = None,
) -> contracts.TaskDetailDTO:
"""Create a task, mirroring ``TaskSerializer.create`` byte-for-byte.
Absorbs the cross-product ``SignalReportTask`` linkage, ``generate_task_title``, and
``resolve_user_github_integration_for_task`` so no internal/other-product import leaks into
presentation. ``validated_data`` carries the validated write fields (integrations already
resolved to instances by the write serializer's PK fields).
``code_access_allowed`` is the caller's Desktop-access outcome, which only the request layer can
evaluate. It upgrades a report discussion from the repo-less exempt shape to a full cloud task:
a resolved repository and the team's GitHub credential. Defaults to ``False`` so a caller that
never ran the gate creates the exempt shape.
"""
from posthog.models import Team # noqa: PLC0415
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product write kept off the api import path
enforce_report_task_cap,
is_pull_request_run_request,
record_report_task,
)
from products.tasks.backend.logic.services.title_generator import generate_task_title # noqa: PLC0415
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
resolve_user_github_integration_for_task,
)
team = Team.objects.get(id=team_id)
validated_data = dict(validated_data)
validated_data["team"] = team
validated_data.setdefault("origin_product", Task.OriginProduct.USER_CREATED)
if (
validated_data.get("channel") is None
and user_id is not None
and not validated_data.get("internal", False)
and validated_data["origin_product"] not in TEAM_READABLE_ORIGIN_PRODUCTS
):
validated_data["channel"] = _ensure_personal_channel(team_id, user_id)[0]
validated_data["client_provenance"] = client_provenance
warm_branch_provided = "branch" in validated_data
warm_branch = validated_data.pop("branch", None)
warm_runtime_adapter = validated_data.pop("runtime_adapter", None)
warm_model = validated_data.pop("model", None)
warm_reasoning_effort = validated_data.pop("reasoning_effort", None)
warm_sandbox_environment_id = validated_data.pop("sandbox_environment_id", None)
warm_custom_image_id = validated_data.pop("custom_image_id", None)
warm_initial_permission_mode = validated_data.pop("initial_permission_mode", None)
pending_user_message = (validated_data.pop("pending_user_message", None) or "").strip() or None
pending_user_artifact_ids = validated_data.pop("pending_user_artifact_ids", None) or []
warm_auto_publish = validated_data.pop("auto_publish", None)
validated_data.pop("scheduled_at", None)
# Names the task from the pasted content while `description` stays the bare prompt. Write-only,
# never persisted, so it must be popped before `Task.objects.create(**validated_data)`.
naming_source = (validated_data.pop("naming_source", None) or "").strip() or None
channel = validated_data.get("channel")
if (
channel is not None
and "repositories" not in validated_data
and "repository" not in validated_data
# A signal_report task's repo must come from the report (resolved below), never a
# channel-carried one, or the code-access exemption runs against an attacker-picked repo.
and validated_data["origin_product"] != Task.OriginProduct.SIGNAL_REPORT
):
validated_data["repositories"] = channel.repositories
validated_data["github_integration"] = channel.github_integration
if "repositories" in validated_data:
repositories = validated_data["repositories"]
validated_data["repository"] = repositories[0] if repositories else None
elif "repository" in validated_data:
validated_data["repositories"] = [validated_data["repository"]] if validated_data["repository"] else []
if user_id is not None:
validated_data["created_by"] = User.objects.get(id=user_id)
if validated_data.get("repository") and not validated_data.get("github_integration"):
default_integration = IntegrationManager.github.oauth.find(team.id)
if default_integration:
validated_data["github_integration"] = default_integration
# The relationship the client asserted (validated by the serializer, which rejects `research`).
# Popped so it isn't forwarded to the model; the link itself is recorded by record_report_task below.
signal_report_task_relationship = validated_data.pop("signal_report_task_relationship", None)
signal_report = validated_data.get("signal_report")
report_discussion = (
validated_data["origin_product"] == Task.OriginProduct.SIGNAL_REPORT
and signal_report is not None
and signal_report_task_relationship not in (None, "implementation")
)
# Reuse is scoped to the submitting origin product: `_find_idling_warm_run` filters on it, so an
# origin that never warms simply finds nothing. The warm call and this create call are separate
# requests that must agree on the origin — when they disagree the lookup misses and we cold-create,
# which costs latency but can never hand over a Run booted under another product's budget or
# PR-authorship rules.
if warm_branch_provided and user_id is not None:
# Post-defaults comparison: warm runs are provisioned with the default triple
# filled in, so the requested selection must be resolved the same way to match.
warm_selection = _with_ai_run_defaults(
{"runtime_adapter": warm_runtime_adapter, "model": warm_model, "reasoning_effort": warm_reasoning_effort},
team_id=team_id,
acting_user_id=user_id,
)
warm_runtime_adapter = warm_selection.get("runtime_adapter")
warm_model = warm_selection.get("model")
warm_reasoning_effort = warm_selection.get("reasoning_effort")
warm_github_integration_id = getattr(validated_data.get("github_integration"), "id", None)
if report_discussion:
warm_github_integration_id = _report_task_github_integration_id(
team, code_access_allowed=code_access_allowed
)
warm_run = (
None
if validated_data["origin_product"] == Task.OriginProduct.SIGNAL_REPORT and not report_discussion
else _find_idling_warm_run(
team_id,
user_id,
origin_product=validated_data["origin_product"],
repository=validated_data.get("repository"),
repositories=validated_data.get("repositories", []),
github_integration_id=warm_github_integration_id,
branch=warm_branch,
runtime_adapter=warm_runtime_adapter,
model=warm_model,
reasoning_effort=warm_reasoning_effort,
sandbox_environment_id=warm_sandbox_environment_id,
custom_image_id=warm_custom_image_id,
initial_permission_mode=warm_initial_permission_mode,
signal_report_id=str(signal_report.id) if report_discussion and signal_report is not None else None,
)
)
if warm_run is not None and not _warm_sandbox_selection_is_accessible(
team_id=team_id,
task_created_by_id=user_id,
sandbox_environment_id=warm_sandbox_environment_id,
custom_image_id=warm_custom_image_id,
):
warm_run = None
if warm_run is not None and pending_user_artifact_ids:
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
get_task_run_artifacts_by_id,
)
_, missing_artifact_ids = get_task_run_artifacts_by_id(warm_run, pending_user_artifact_ids)
if missing_artifact_ids:
logger.info(
"Skipping warm run reuse: %d pending artifact id(s) missing from warm run %s manifest",
len(missing_artifact_ids),
warm_run.id,
)
warm_run = None
if warm_run is not None:
if Team.objects.filter(id=team_id, organization__is_pending_deletion=True).exists():
raise PermissionDenied(
"This organization is scheduled for deletion. Select another organization to run tasks."
)
_warm_retry_message_id(warm_retry_token, warm_run)
warm_task = warm_run.task
should_set_client_provenance = warm_task.client_provenance is None and client_provenance is not None
if should_set_client_provenance:
warm_task.client_provenance = client_provenance
from products.tasks.backend.exceptions import (
ComputeBillingLimitError, # noqa: PLC0415 — keep temporalio off the api import path
)
from products.tasks.backend.logic.services.compute_quota import ( # noqa: PLC0415
get_compute_quota_denial_reason,
)
if reason := get_compute_quota_denial_reason(warm_task):
raise ComputeBillingLimitError(
{"team_id": team_id, "task_id": str(warm_task.id), "run_id": str(warm_run.id)}, reason
)
if (cap_detail := _active_session_cap_refusal(warm_task)) is not None:
raise ActiveSessionCapRefused(cap_detail)
report_reservation = (
_reserve_report_warm_activation(
team,
warm_task,
relationship=signal_report_task_relationship,
description=validated_data.get("description"),
)
if report_discussion
else None
)
description = (validated_data.get("description") or "").strip()
requested_title = (validated_data.get("title") or "").strip()
update_fields: list[str] = []
if "created_on_mobile" not in (warm_task.state or {}):
warm_task.state = {**(warm_task.state or {}), **validated_data.get("state", {})}
update_fields.append("state")
if requested_title and not (warm_task.title or "").strip():
warm_task.title = requested_title
warm_task.title_manually_set = True
update_fields += ["title", "title_manually_set"]
elif description and not (warm_task.title or "").strip():
warm_task.title = generate_task_title(naming_source or description)
warm_task.title_manually_set = False
update_fields += ["title", "title_manually_set"]
if description and not (warm_task.description or "").strip():
warm_task.description = description
update_fields.append("description")
channel = validated_data.get("channel")
if channel is not None and warm_task.channel_id != channel.id:
warm_task.channel = channel
update_fields.append("channel")
if update_fields:
warm_task.save(update_fields=[*update_fields, "updated_at"])
if should_set_client_provenance:
Task.objects.filter(id=warm_task.id, client_provenance__isnull=True).update(
client_provenance=client_provenance
)
try:
_activate_warm_run(
warm_run,
warm_task,
team_id,
message=pending_user_message or description or None,
branch=warm_branch,
description=description or None,
artifact_ids=pending_user_artifact_ids,
auto_publish=warm_auto_publish,
reasoning_effort=warm_reasoning_effort,
retry_token=warm_retry_token,
)
except Exception:
if report_reservation is not None:
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product write kept off the api import path
delete_report_task_artefact,
)
delete_report_task_artefact(team_id=warm_task.team_id, artefact_id=report_reservation)
raise
return _task_detail_to_dto(_task_detail_queryset().get(pk=warm_task.pk))
if warm_retry_token is not None:
raise WarmRunActivationUnavailable("target_unavailable")
refuse_without_repository = False
# Inbox "Create PR" doesn't pre-select a repo, so resolve one here rather than creating a
# report-linked task that can never open a PR. "Implementation" (Create PR) and legacy clients
# (no relationship) always resolve one. "Discuss" (and any other non-implementation label)
# starts repo-less: the sandbox boots without a clone and the agent clones on demand with the
# credential an entitled caller's task carries (see `task_exempt_from_code_access`).
if (
signal_report is not None
and not validated_data.get("repository")
and validated_data.get("origin_product") == Task.OriginProduct.SIGNAL_REPORT
and signal_report_task_relationship in (None, "implementation")
):
from products.signals.backend.facade.api import ( # noqa: PLC0415 — cross-product read kept off the api import path
persisted_repo_selection,
)
from products.tasks.backend.logic.repo_selection.cascade import ( # noqa: PLC0415 — keeps repo-selection agent imports lazy
cascade_select_repository,
)
# A named selection wins. A no-repo selection (`repository=None`) does not: autostart
# already honors it in signals (it never creates a task without a repository), so reaching
# here means a person clicked "Create PR", which is the stronger signal. Fall through to
# the cascade rather than create a task whose sandbox can only read, never push.
selection = persisted_repo_selection(str(signal_report.id))
resolved_repository = selection.repository if selection is not None else None
if not resolved_repository:
resolved_repository = cascade_select_repository(
team_id,
user_id,
validated_data.get("description") or "",
team=team,
single_repo_wins=True,
allow_refresh=False,
)
if selection is not None:
_capture_no_repo_selection_override(
team=team,
report_id=str(signal_report.id),
resolved_repository=resolved_repository,
relationship=signal_report_task_relationship,
)
if resolved_repository:
validated_data["repository"] = resolved_repository
refuse_without_repository = (
not resolved_repository and client_provenance != TaskClientProvenance.POSTHOG_DESKTOP
)
# The credential follows the entitlement, not the repository: an entitled report task carries
# the team's GitHub integration even when nothing resolved, so the agent can still clone what
# the conversation turns out to need. That is the shape a repo-less user-created task already
# has, and provisioning keys the token off the attached integration, so a task created without
# the gate stays credential-less.
entitled_report_task = (
code_access_allowed
and signal_report is not None
and validated_data.get("origin_product") == Task.OriginProduct.SIGNAL_REPORT
)
if (validated_data.get("repository") or entitled_report_task) and not validated_data.get("github_integration"):
if signal_report is not None:
integration_id = _report_task_github_integration_id(team, code_access_allowed=True)
default_integration = (
_team_github_integration_or_none(team.id, integration_id) if integration_id is not None else None
)
else:
default_integration = IntegrationManager.github.oauth.find(team.id)
if default_integration:
validated_data["github_integration"] = default_integration
if (
validated_data.get("repository")
and validated_data.get("origin_product", Task.OriginProduct.USER_CREATED) == Task.OriginProduct.USER_CREATED
and not validated_data.get("github_user_integration")
):
task_stub = Task(
team=team,
created_by=validated_data.get("created_by"),
origin_product=Task.OriginProduct.USER_CREATED,
repository=validated_data["repository"],
github_integration=validated_data.get("github_integration"),
)
github_user_integration = resolve_user_github_integration_for_task(task_stub, allow_refresh=False)
if github_user_integration is not None:
validated_data["github_user_integration"] = github_user_integration.integration
if validated_data["origin_product"] == Task.OriginProduct.ACCOUNT_AUDIT:
validated_data["repository"] = None
validated_data["repositories"] = []
validated_data.pop("github_integration", None)
validated_data.pop("github_user_integration", None)
title = (validated_data.get("title") or "").strip()
if not title and (naming_source or validated_data.get("description")):
validated_data["title"] = generate_task_title(naming_source or validated_data["description"])
validated_data.setdefault("title_manually_set", False)
elif title:
validated_data.setdefault("title_manually_set", True)
# The write serializer binds the report as `signal_report` (a PK field); direct callers may
# pass `signal_report_id`. Either way this is the manual "start work from a report" path.
report_ref = validated_data.get("signal_report") or validated_data.get("signal_report_id")
signal_report_id = (
str(getattr(report_ref, "id", report_ref))
if report_ref and validated_data.get("origin_product") == Task.OriginProduct.SIGNAL_REPORT
else None
)
if signal_report_id and (
signal_report_task_relationship in (None, "implementation")
or is_pull_request_run_request(validated_data.get("description"))
):
enforce_self_driving_free_trial(team, report_id=signal_report_id)
if refuse_without_repository and signal_report is not None:
_capture_report_task_refused_without_repository(team=team, report_id=str(signal_report.id))
raise ValidationError({"repository": REPORT_IMPLEMENTATION_REPOSITORY_UNRESOLVED})
if signal_report is not None and signal_report_task_relationship in (None, "implementation"):
from products.signals.backend.facade.github_optional import ( # noqa: PLC0415 - keeps the signals model graph out of tasks facade initialization
github_optional_pilot_enabled,
pilot_repository_integration_id,
)
if github_optional_pilot_enabled(team_id):
integration_id = (
pilot_repository_integration_id(team_id, validated_data["repository"])
if validated_data.get("repository")
else None
)
pilot_integration = (
_team_github_integration_or_none(team_id, integration_id) if integration_id is not None else None
)
if pilot_integration is None:
raise ValidationError(
{
"repository": "Connect or repair GitHub access to the selected repository before creating a pull request."
}
)
validated_data["github_integration"] = pilot_integration
if report_ref:
validated_data["source_kind"] = SourceKind.SIGNAL_REPORT.value
validated_data["source_id"] = str(getattr(report_ref, "id", report_ref))
if validated_data.get("origin_key") is not None:
validated_data["idempotency_key"] = validated_data["origin_key"]
logger.info("Creating task with data: %s", validated_data)
with transaction.atomic():
if signal_report_id:
# Locks the report row until commit, so concurrent creates (and auto-start, which
# takes the same lock) serialize instead of both passing the count check.
enforce_report_task_cap(
team_id=team_id,
report_id=signal_report_id,
relationship=signal_report_task_relationship,
description=validated_data.get("description"),
created_by_id=user_id,
)
task = Task.objects.create(**validated_data)
if task.signal_report_source_id and task.origin_product == Task.OriginProduct.SIGNAL_REPORT:
# Record the task↔report association + work-log artefact for the asserted relationship
# (defaults to implementation, which also writes the auto-start spend gate row) so a
# manually-started task matches autostarted ones.
record_report_task(
team_id=task.team_id,
report_id=str(task.signal_report_source_id),
task_id=str(task.id),
relationship=signal_report_task_relationship,
)
# Only an override is a change. The inherited case is already counted by `task_created`.
if channel is not None and repositories_differ(channel.repositories, task.repositories):
capture_repository_config_changed(
team=team,
user_id=user_id,
subject="task",
trigger="task_created",
previous_repositories=channel.repositories,
repositories=task.repositories,
previous_integration_id=channel.github_integration_id,
integration_id=task.github_integration_id,
channel_id=str(channel.id),
task_id=str(task.id),
origin_product=task.origin_product,
space_repositories=channel.repositories,
)
if signal_report_id and signal_report_task_relationship in (None, "implementation") and task.repository:
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product write kept off the api import path
create_tracker_issue_for_report,
)
create_tracker_issue_for_report(
team_id=team_id,
report_id=signal_report_id,
repository=task.repository,
)
return _task_detail_to_dto(_task_detail_queryset().get(pk=task.pk))
def set_task_title(task_id: str | UUID, team_id: int, title: str) -> bool:
"""Set a task's title, team-scoped. For automated relabels — e.g. backfilling a Signals research
task with ``"Research: <report title>"`` once research produces the title. Leaves
``title_manually_set`` untouched (this isn't a user edit) and clamps to the column length. Returns
whether a row was updated.
"""
task = Task.objects.filter(id=task_id, team_id=team_id).first()
if task is None:
return False
task.title = title[:255]
task.save(update_fields=["title"])
return True
def update_task(
task_id: str | UUID, team_id: int, user_id: int | None, *, validated_data: dict
) -> contracts.TaskDetailDTO | None:
"""Update a task, mirroring ``TaskSerializer.update``. ``None`` if not found/controllable."""
validated_data = dict(validated_data)
# origin_product controls visibility and signal_report is set once.
validated_data.pop("signal_report", None)
validated_data.pop("signal_report_task_relationship", None)
validated_data.pop("origin_product", None)
validated_data.pop("branch", None)
with transaction.atomic():
task = Task.objects.select_for_update().filter(id=task_id, team_id=team_id, deleted=False).first()
if task is None or not Task.objects.filter(id=task.id).filter(task_control_q(user_id)).exists():
return None
if not _task_drive_allowed(task, user_id):
return None
previous_repositories = list(task.repositories or [])
previous_integration_id = task.github_integration_id
# Repo and credential are immutable for code-access-exempt tasks: a mutable repo reopens the
# gate (see task_exempt_from_code_access), and provisioning injects whatever integration is
# attached, so an attachable one would credential a run the create path left credential-less.
if task.origin_product in (
Task.OriginProduct.SIGNALS_CHAT,
Task.OriginProduct.SIGNAL_REPORT,
Task.OriginProduct.ACCOUNT_AUDIT,
):
validated_data.pop("repository", None)
validated_data.pop("repositories", None)
validated_data.pop("github_integration", None)
validated_data.pop("github_user_integration", None)
if "repositories" in validated_data:
repositories = validated_data["repositories"]
validated_data["repository"] = repositories[0] if repositories else None
elif "repository" in validated_data:
if len(task.repositories) <= 1:
validated_data["repositories"] = [validated_data["repository"]] if validated_data["repository"] else []
else:
validated_data.pop("repository")
profile = task.stored_profile
changes_github_access = not validated_data.keys().isdisjoint(
{"repository", "repositories", "github_integration", "github_user_integration"}
)
github_access = task.github_access_limit
if (
(profile is not None or github_access == GithubAccess.NONE)
and changes_github_access
and not Task.attaches_github(
task.origin_product,
profile,
has_repository=bool(validated_data.get("repository", task.repository)),
github_access=github_access,
)
):
validated_data.pop("github_integration", None)
validated_data.pop("github_user_integration", None)
task.github_integration = None
task.github_user_integration = None
if "title" in validated_data and "title_manually_set" not in validated_data:
validated_data["title_manually_set"] = True
if "archived" in validated_data and validated_data["archived"] != task.archived:
validated_data["archived_at"] = django_timezone.now() if validated_data["archived"] else None
repo_fields_touched = any(key in validated_data for key in ("repositories", "repository", "github_integration"))
logger.info("perform_update called for task %s with validated_data: %s", task.id, validated_data)
for key, value in validated_data.items():
setattr(task, key, value)
github_fields_touched = repo_fields_touched or "github_user_integration" in validated_data
if github_fields_touched and not Task._github_resolution_allowed(
task.origin_product, has_repository=bool(task.repositories or task.repository)
):
task.github_integration = None
task.github_user_integration = None
task.save()
logger.info("Task %s updated successfully", task.id)
if repo_fields_touched:
space_repositories = (
Channel.objects.filter(id=task.channel_id).values_list("repositories", flat=True).first()
if task.channel_id
else None
)
capture_repository_config_changed(
team=task.team,
user_id=user_id,
subject="task",
trigger="task_settings_edit",
previous_repositories=previous_repositories,
repositories=task.repositories,
previous_integration_id=previous_integration_id,
integration_id=task.github_integration_id,
channel_id=str(task.channel_id) if task.channel_id else None,
task_id=str(task.id),
origin_product=task.origin_product,
space_repositories=space_repositories,
)
return _task_detail_to_dto(_task_detail_queryset().get(pk=task.pk))
def soft_delete_task(task_id: str | UUID, team_id: int, user_id: int | None) -> bool:
"""Soft-delete a task. Returns whether a task was found/controllable and deleted."""
with transaction.atomic():
task = Task.objects.select_for_update().filter(id=task_id, team_id=team_id, deleted=False).first()
if task is None or not Task.objects.filter(id=task.id).filter(task_control_q(user_id)).exists():
return False
if not _task_drive_allowed(task, user_id):
return False
logger.info("Soft deleting task %s", task.id)
task.soft_delete()
soft_delete_conversations_for_task(task.id)
return True
# --- Task handoff (transfer ownership to a colleague) ---
class TaskHandoffError(Exception):
"""A handoff request that reads as a client error rather than a missing task."""
def handoff_task(
task_id: str | UUID, team_id: int, user_id: int | None, *, target_user_id: int
) -> contracts.TaskDetailDTO | None:
task = _visible_task_qs(team_id, user_id, for_control=True).filter(id=task_id).first()
if task is None:
return None
if user_id is None or task.created_by_id != user_id:
return None
if not _task_drive_allowed(task, user_id):
return None
if task.created_by_id == target_user_id:
raise TaskHandoffError("That person already owns this task.")
previous_owner_id = task.created_by_id
actor = User.objects.filter(id=user_id).only("first_name", "email", "distinct_id").first() if user_id else None
actor_name = ((actor.first_name.strip() or actor.email) if actor else None) or "Someone"
channel = task.channel
with transaction.atomic():
if channel is not None and channel.channel_type == Channel.ChannelType.PRIVATE:
if _locked_visible_channel(channel.id, team_id, user_id, no_key=True) is None:
return None
locked = Task.objects.select_for_update().get(pk=task.pk)
if locked.deleted or locked.channel_id != task.channel_id:
return None
if locked.created_by_id != previous_owner_id:
raise TaskHandoffError("Someone else has already handed this task off. Refresh and try again.")
if locked.is_scout_experiment:
raise TaskHandoffError("Scout comparison tasks stay with the operator who launched them.")
if not Task.objects.filter(id=locked.id).filter(task_control_q(user_id)).exists():
return None
target = locked.team.all_users_with_access().filter(id=target_user_id).first()
if target is None:
raise TaskHandoffError("Tasks can only be handed off to someone with access to this project.")
target_name = target.first_name.strip() or target.email
if (
TaskRun.objects.filter(task_id=locked.id, team_id=team_id)
.exclude(status__in=[TaskRun.Status.COMPLETED, TaskRun.Status.FAILED, TaskRun.Status.CANCELLED])
.exists()
):
raise TaskHandoffError("Finish or cancel active runs before handing off this task.")
if (
SandboxSession.objects.for_team(team_id)
.filter(
task_run__task_id=locked.id,
ended_at__isnull=True,
ttl_expires_at__gt=django_timezone.now(),
)
.exists()
):
raise TaskHandoffError("Wait for active sandboxes to shut down before handing off this task.")
bound_tokens = OAuthAccessToken.objects.filter(sandbox_task_id=locked.id)
OAuthRefreshToken.objects.filter(access_token__in=bound_tokens).delete()
bound_tokens.delete()
detach_conversations_for_task_handoff(locked.id, target.id)
channel = locked.channel
if channel is None or channel.channel_type == Channel.ChannelType.PERSONAL:
locked.channel = _ensure_personal_channel(team_id, target.id)[0]
elif channel.channel_type == Channel.ChannelType.PRIVATE:
ChannelMembership.objects.for_team(team_id).get_or_create(
channel_id=channel.id, user_id=target.id, defaults={"team_id": team_id}
)
locked.created_by = target
if locked.github_user_integration_id is not None:
locked.github_user_integration = None
locked.state = {
key: value for key, value in (locked.state or {}).items() if key != MCP_CREDENTIAL_OWNER_STATE_KEY
}
locked.state[TASK_OWNERSHIP_VERSION_STATE_KEY] = str(uuid4())
locked.save()
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product write kept off the api import path
queue_task_handoff_claims,
)
# After commit, so the report locks it takes are never waited on while this task row is locked.
transaction.on_commit(
partial(
queue_task_handoff_claims,
team_id=team_id,
task_id=str(locked.id),
previous_user_id=user_id,
)
)
message = TaskThreadMessage.objects.for_team(team_id).create(
team_id=team_id,
task_id=locked.id,
author_id=user_id,
author_kind=TaskThreadMessage.AuthorKind.SYSTEM,
event="task_handed_off",
payload={
"from_user_id": previous_owner_id,
"to_user_id": target.id,
"from_display_name": actor_name if user_id is not None else None,
"to_display_name": target_name,
},
content=f"{actor_name} handed this task off to {target_name}",
)
try:
project_thread_message_activity(message)
except Exception:
logger.exception("Failed to project handoff thread activity", extra={"task_id": str(task_id)})
from products.tasks.backend.push_dispatcher import (
notify_task_handoff, # noqa: PLC0415 — optional push dep stays off the import path
)
notify_task_handoff(locked, recipient=target, actor=actor, message_id=message.id)
try:
posthoganalytics.capture(
distinct_id=str(actor.distinct_id) if actor is not None and actor.distinct_id else str(locked.team.uuid),
event="task_handed_off",
properties={
"task_id": str(locked.id),
"team_id": locked.team_id,
"title": locked.title,
"origin_product": locked.origin_product,
"repository": locked.repository,
"from_user_id": previous_owner_id,
"to_user_id": target.id,
},
groups=groups(team=locked.team),
send_feature_flags=True,
)
except Exception as e:
logger.warning("task_handed_off capture_event failed for task %s: %s", locked.id, e)
return _task_detail_to_dto(_task_detail_queryset().get(pk=locked.pk))
# --- Task staged artifacts (S3 + cache, attached to the next run) ---
_TASK_STAGED_ARTIFACT_UPLOAD_FORM_OVERHEAD_BYTES = 64 * 1024
def prepare_task_staged_artifacts(
task_id: str | UUID,
team_id: int,
user_id: int | None,
*,
artifacts: list[dict],
upload_expiration_seconds: int,
) -> contracts.StagedArtifactPrepareResult | None:
"""Reserve S3 keys + presigned POST forms for task attachments. ``None`` if task not found."""
from posthog.storage import object_storage # noqa: PLC0415
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415
build_task_staged_artifact_storage_path,
get_safe_artifact_name,
)
# Staged artifacts feed the task's next run, so this is control, not viewing.
task = _visible_task_qs(team_id, user_id, for_control=True).filter(id=task_id).first()
if task is None or not _task_drive_allowed(task, user_id):
return None
prepared: list[contracts.StagedArtifactPreparedDTO] = []
for artifact in artifacts:
artifact_id = uuid4().hex
safe_name = get_safe_artifact_name(artifact["name"])
storage_path = build_task_staged_artifact_storage_path(task, artifact_id, safe_name)
presigned_post = object_storage.get_presigned_post(
storage_path,
conditions=[
["content-length-range", 0, artifact["size"] + _TASK_STAGED_ARTIFACT_UPLOAD_FORM_OVERHEAD_BYTES]
],
expiration=upload_expiration_seconds,
)
if not presigned_post:
return contracts.StagedArtifactPrepareResult(error="Unable to generate upload URL")
prepared.append(
contracts.StagedArtifactPreparedDTO(
id=artifact_id,
name=safe_name,
type=artifact["type"],
source=artifact.get("source") or "",
size=artifact["size"],
content_type=artifact.get("content_type") or "",
storage_path=storage_path,
expires_in=upload_expiration_seconds,
presigned_post=presigned_post,
metadata=artifact.get("metadata"),
)
)
return contracts.StagedArtifactPrepareResult(artifacts=prepared)
def finalize_task_staged_artifacts(
task_id: str | UUID,
team_id: int,
user_id: int | None,
*,
artifacts: list[dict],
) -> contracts.StagedArtifactFinalizeResult | None:
"""Verify staged S3 uploads and cache their metadata. ``None`` if task not found."""
from django.conf import settings # noqa: PLC0415
from posthog.storage import object_storage # noqa: PLC0415
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415
STAGED_ARTIFACT_TTL_DAYS,
build_task_artifact_entry,
cache_task_staged_artifact,
get_safe_artifact_name,
tag_task_artifact,
)
from products.tasks.backend.presentation.serializers import ( # noqa: PLC0415
build_task_run_artifact_size_error,
get_task_run_artifact_max_size_bytes,
)
task = _visible_task_qs(team_id, user_id, for_control=True).filter(id=task_id).first()
if task is None or not _task_drive_allowed(task, user_id):
return None
artifact_prefix = f"{settings.OBJECT_STORAGE_TASKS_FOLDER}/artifacts/team_{task.team_id}/task_{task.id}/staged/"
finalized: list[dict] = []
for artifact in artifacts:
artifact_id = artifact["id"]
storage_path = artifact["storage_path"]
if not storage_path.startswith(artifact_prefix) or f"/{artifact_id}/" not in storage_path:
return contracts.StagedArtifactFinalizeResult(error="Artifact storage path is invalid for this task")
s3_object = object_storage.head_object(storage_path)
if not s3_object:
return contracts.StagedArtifactFinalizeResult(error="Artifact upload not found in object storage")
content_length = s3_object.get("ContentLength")
if not isinstance(content_length, int):
return contracts.StagedArtifactFinalizeResult(error="Artifact upload metadata is unavailable")
safe_name = get_safe_artifact_name(artifact["name"])
content_type = artifact.get("content_type") or s3_object.get("ContentType") or ""
max_size_bytes = get_task_run_artifact_max_size_bytes(safe_name, content_type, artifact.get("type"))
if content_length > max_size_bytes:
return contracts.StagedArtifactFinalizeResult(
error=build_task_run_artifact_size_error(safe_name, max_size_bytes)
)
finalized.append(
build_task_artifact_entry(
artifact_id=artifact_id,
name=safe_name,
artifact_type=artifact["type"],
source=artifact.get("source") or "",
size=content_length,
content_type=content_type,
storage_path=storage_path,
metadata=artifact.get("metadata"),
)
)
for entry in finalized:
cache_task_staged_artifact(task, entry)
tag_task_artifact(entry["storage_path"], ttl_days=STAGED_ARTIFACT_TTL_DAYS, team_id=task.team_id)
return contracts.StagedArtifactFinalizeResult(artifacts=finalized)
def resolve_team_github_integration_id(team_id: int, github_integration_id: int) -> int | None:
"""Return the integration id only if it is a GitHub integration owned by this team.
Re-scoping guard for the collection-level warm endpoint, which accepts a bare PK with
no serializer team context. Returns ``None`` for any id that doesn't belong to the team —
the caller treats that as "skip warming" (the submit later falls through to a cold create+run).
"""
try:
IntegrationManager.github.oauth.get(team_id, github_integration_id)
except IntegrationNotFound:
return None
return github_integration_id
def can_mint_readonly_github_token(team_id: int) -> bool:
"""Whether a repo-less sandbox requesting `github_read_access` would actually get a token.
Preflight for callers that condition user-visible behavior (e.g. prompt guidance naming `gh`)
on the read-only token being obtainable — true only when the team has a usable team-level
GitHub installation. Never raises.
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keeps the temporal stack off the facade import path
can_mint_readonly_github_token as _can_mint,
)
return _can_mint(team_id)
def readonly_github_integration_id(team_id: int) -> int | None:
"""Id of the GitHub integration a read-only sandbox token would be minted from, or ``None``.
Pairs with :func:`can_mint_readonly_github_token` for callers that must validate repository
names against the credential a downscoped run will actually hold, because a repository the
mintable installation cannot reach is a clone that fails mid-run. Team-level installations only, same
rule as the mint. Never raises.
"""
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keeps the temporal stack off the facade import path
resolve_readonly_github_integration,
)
integration = resolve_readonly_github_integration(team_id)
return integration.integration.id if integration is not None else None
def _with_ai_run_defaults(
data: dict,
*,
team_id: int,
acting_user_id: int | None,
internal: bool = False,
runtime: str = Task.Runtime.ACP,
) -> dict:
"""A copy of ``data`` with the team/user default AI run triple filled in when it pins
no runtime selection (see ``resolve_ai_run_selection``).
Applied ahead of warm-run matching so requests and warm runs compare post-defaults —
a warm run provisioned under the default triple must match a submit that pinned
nothing. ``Task.create_run`` applies the same resolution as a safety net for every
other path, so this is deterministic double-resolution, not a divergence.
"""
if internal:
return data
from products.tasks.backend.logic.services.ai_run_defaults import ( # noqa: PLC0415 — keep ORM-heavy logic services off the api import path
apply_ai_run_defaults,
)
updated = dict(data)
apply_ai_run_defaults(updated, team_id, acting_user_id, runtime=runtime)
return updated
def _find_idling_warm_run(
team_id: int,
user_id: int | None,
*,
origin_product: str,
repository: str | None,
repositories: list[str] | None = None,
github_integration_id: int | None,
branch: str | None,
runtime_adapter: str | None = None,
model: str | None = None,
reasoning_effort: str | None = None,
sandbox_environment_id: str | UUID | None = None,
custom_image_id: str | UUID | None = None,
initial_permission_mode: str | None = None,
signal_report_id: str | UUID | None = None,
) -> TaskRun | None:
"""Most-recent idling pre-warmed Run matching this user's cloud composing selection, or ``None``.
A warm Run is a non-terminal Run of the same origin product, for the same optional repo+branch, still
awaiting its first user message (the ``await_user_message`` state marker). This is the backend's single
source of truth for the warm pool: it dedupes warm provisioning (so a repeated ``warm`` call reuses the
live Run instead of spawning a second) and lets the normal create+run path transparently reuse a
warm Run on submit. Team + user scoped; branch compared as ``None``-normalized exact match.
``origin_product`` is required and never defaulted: it selects the OAuth app, the warm quota gate, the
pool caps, and PR authorship, all of which are fixed when the warm boots and cannot be changed at
activation. Matching across origins would hand a Run provisioned under one product's budget and
authorship rules to another.
Reuse also requires the warm Run's runtime, model, sandbox environment, and custom image selections to
match the request, plus its permission mode when the caller states one. Reasoning effort is deliberately
excluded: activation applies the final effort before the first turn. Other mismatches return ``None`` so
the caller cold-creates on the correct sandbox.
The optional repo/branch/``await_user_message`` predicates stay in the query; the remaining selection is
matched in Python over the small candidate set.
"""
if user_id is None:
return None
normalized_repositories = [repo.lower() for repo in (repositories or ([repository] if repository else []))]
repository_filter = {"task__repository__iexact": repository} if repository else {"task__repository__isnull": True}
report_filter = source_q(SourceKind.SIGNAL_REPORT, [signal_report_id], via="task__") if signal_report_id else Q()
candidates = (
TaskRun.objects.filter( # nosemgrep: idor-lookup-without-team — team_id filter applied via the task FK below
report_filter,
task__team_id=team_id,
task__created_by_id=user_id,
task__origin_product=origin_product,
task__deleted=False,
task__github_integration_id=github_integration_id,
state__await_user_message=True,
**({"state__billing_product": "posthog_ai"} if origin_product == Task.OriginProduct.SIGNAL_REPORT else {}),
branch=branch or None,
**repository_filter,
)
.exclude(status__in=_TERMINAL_TASK_RUN_STATUSES)
.select_related("task")
.order_by("-created_at")[:20]
)
wanted = (
runtime_adapter or None,
model or None,
str(sandbox_environment_id) if sandbox_environment_id else None,
str(custom_image_id) if custom_image_id else None,
)
for run in candidates:
state = run.state or {}
if state.get("cancel_requested_at"):
continue
have_repositories = [
repo.lower() for repo in (run.task.repositories or ([run.task.repository] if run.task.repository else []))
]
if have_repositories != normalized_repositories:
continue
have = (
state.get("runtime_adapter") or None,
state.get("model") or None,
state.get("sandbox_environment_id") or None,
state.get("custom_image_id") or None,
)
if have != wanted:
continue
# Asymmetric on purpose, and load-bearing: a warm Run's state ALWAYS holds a concrete permission
# mode (warm_task_sandbox writes one unconditionally), while callers that never send one — the
# Code app — must keep reusing their warms. Folding this into the tuple above would compare None
# against "default" and break every one of those reuses.
if initial_permission_mode is not None and state.get("initial_permission_mode") != initial_permission_mode:
continue
return run
return None
def _warm_sandbox_selection_is_accessible(
*,
team_id: int,
task_created_by_id: int | None,
sandbox_environment_id: str | UUID | None,
custom_image_id: str | UUID | None,
) -> bool:
if sandbox_environment_id is not None:
sandbox_environment = SandboxEnvironment.get_accessible_for_task(
environment_id=sandbox_environment_id,
team_id=team_id,
task_created_by_id=task_created_by_id,
)
if sandbox_environment is None:
return False
if custom_image_id is not None:
custom_image = SandboxCustomImage.get_accessible_for_task(
image_id=custom_image_id,
team_id=team_id,
task_created_by_id=task_created_by_id,
)
if custom_image is None or not custom_image.is_ready:
return False
return True
def _idling_warm_run_for_task(task: Task) -> TaskRun | None:
"""The task's latest run iff it is an idling pre-warmed Run (non-terminal, awaiting first message)."""
run = task.latest_run
if run is None or run.is_terminal or (run.state or {}).get("cancel_requested_at"):
return None
if (
task.origin_product == Task.OriginProduct.SIGNAL_REPORT
and (run.state or {}).get("billing_product") != "posthog_ai"
):
return None
if not (run.state or {}).get("await_user_message"):
return None
return run
def _attach_staged_artifacts_to_run(
run: TaskRun, task: Task, *, staged_artifacts: list[dict], artifact_ids: list[str]
) -> None:
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415 — keep storage deps off the api import path
RUN_ARTIFACT_TTL_DAYS,
build_task_staged_artifact_cache_key,
tag_task_artifact,
)
from products.tasks.backend.redis import get_tasks_cache # noqa: PLC0415
manifest = list(run.artifacts or [])
for staged_artifact in staged_artifacts:
storage_path = str(staged_artifact["storage_path"])
if _find_artifact_manifest_entry(manifest, str(staged_artifact.get("id")), storage_path):
continue
# Scheduled attachments are tagged before the run-creation transaction takes its locks.
if run.scheduled_at is None:
tag_task_artifact(storage_path, ttl_days=RUN_ARTIFACT_TTL_DAYS, team_id=task.team_id)
manifest.append(dict(staged_artifact))
_save_artifact_manifest(run, manifest)
cache_keys = [build_task_staged_artifact_cache_key(str(task.id), artifact_id) for artifact_id in artifact_ids]
if run.scheduled_at is not None:
transaction.on_commit(lambda: get_tasks_cache().delete_many(cache_keys), robust=True)
else:
get_tasks_cache().delete_many(cache_keys)
REPORT_WARM_RUN_NOT_ACTIVATED = "This sandbox is waiting for the report's Ask AI question. Send it from the report."
REPORT_IMPLEMENTATION_REPOSITORY_UNRESOLVED = (
"Couldn't tell which GitHub repository this report is about, so there is nowhere to open a PR. "
"Name the repository in the instructions for the PostHog agent (for example, owner/repo) and try again."
)
ACTIVE_SESSION_CAP_CODE = "active_session_cap"
class ActiveSessionCapRefused(Exception):
code = ACTIVE_SESSION_CAP_CODE
def __init__(self, detail: str) -> None:
self.detail = detail
super().__init__(detail)
class WarmRunActivationUnavailable(Exception):
code = "warm_run_activation_unavailable"
def __init__(self, reason: str) -> None:
self.reason = reason
self.retry_token: str | None = None
super().__init__("Couldn't start this run yet. Please try again.")
def _warm_retry_message_id(token: str | None, run: TaskRun) -> str | None:
if token is None:
return None
try:
run_id, workflow_id, message_id = signing.TimestampSigner(salt="warm-run-activation").unsign_object(
token, max_age=60
)
except (signing.BadSignature, ValueError) as error:
raise WarmRunActivationUnavailable("invalid_retry") from error
if run_id != str(run.id) or workflow_id != run.workflow_id:
raise WarmRunActivationUnavailable("target_unavailable")
return str(message_id)
def _deliver_warm_run_message(
run: TaskRun, *, message: str | None, artifact_ids: list[str], message_id: str | None = None
) -> None:
from temporalio.service import RPCError, RPCStatusCode
started_at = time.monotonic()
workflow_id = run.workflow_id
frontend_retry = message_id is not None
message_id = message_id or str(uuid4())
eligible_runs = TaskRun.objects.filter(
id=run.id,
team_id=run.team_id,
task_id=run.task_id,
task__deleted=False,
state__await_user_message=True,
).exclude(status__in=_TERMINAL_TASK_RUN_STATUSES)
try:
with transaction.atomic():
current_run = eligible_runs.select_for_update(of=("self",)).first()
if (
current_run is None
or current_run.workflow_id != workflow_id
or (current_run.state or {}).get("cancel_requested_at")
):
raise WarmRunActivationUnavailable("target_unavailable")
# Claim before signaling so a different composer's release cannot cancel delivery in flight.
current_run.state["warm_activation_started"] = True
current_run.save(update_fields=["state", "updated_at"])
try:
delivered = signal_task_run_user_message(
run.id,
run.task_id,
run.team_id,
content=message,
artifact_ids=artifact_ids,
message_id=message_id,
workflow_id=workflow_id,
rpc_timeout=timedelta(seconds=10),
)
except RPCError as error:
# NOT_FOUND proves the workflow did not receive this message. Other errors may follow delivery.
if error.status != RPCStatusCode.NOT_FOUND:
raise
current_run = eligible_runs.first()
if current_run is None or current_run.workflow_id != workflow_id:
raise WarmRunActivationUnavailable("target_unavailable") from error
unavailable = WarmRunActivationUnavailable("starting")
unavailable.retry_token = signing.TimestampSigner(salt="warm-run-activation").sign_object(
[str(run.id), workflow_id, message_id]
)
raise unavailable from error
if delivered is not True:
raise WarmRunActivationUnavailable("delivery_failed")
with transaction.atomic():
task = Task.objects.select_for_update().get(id=run.task_id)
activated_run = eligible_runs.select_for_update(of=("self",)).first()
if activated_run is None or activated_run.workflow_id != workflow_id:
raise WarmRunActivationUnavailable("target_unavailable")
activated_run.state.pop("await_user_message", None)
activated_run.state["warm_activated"] = True
activated_run.save(update_fields=["state", "updated_at"])
task.observe_run_started_beside_live_runs(activated_run)
except WarmRunActivationUnavailable as error:
log = logger.info if error.retry_token else logger.warning
log(
"task_warm_activation_unavailable",
extra={
"run_id": str(run.id),
"task_id": str(run.task_id),
"team_id": run.team_id,
"workflow_id": workflow_id,
"elapsed_seconds": time.monotonic() - started_at,
"reason": error.reason,
"frontend_retry": frontend_retry,
},
)
raise
if frontend_retry:
logger.info(
"task_warm_activation_recovered",
extra={
"run_id": str(run.id),
"task_id": str(run.task_id),
"team_id": run.team_id,
"workflow_id": workflow_id,
"elapsed_seconds": time.monotonic() - started_at,
"frontend_retry": frontend_retry,
},
)
def _activate_warm_run(
run: TaskRun,
task: Task,
team_id: int,
*,
message: str | None,
branch: str | None,
artifact_ids: list[str],
description: str | None = None,
auto_publish: bool | None = None,
reasoning_effort: str | None = None,
retry_token: str | None = None,
) -> None:
"""Activate an idling warm Run: set the draft Task's visible description from raw task text,
forward the first message to the already-running agent, and drop the ``await_user_message`` marker
so the Run leaves the warm pool. Mirrors ``message_routing._handle_first_message``; no fresh agent
start.
``auto_publish`` is persisted into the Run's state before the message signal: the already-running
agent-server can't take it as a launch flag, so it re-reads run state when the forwarded first
message arrives (and resumes read it from carried state)."""
from products.tasks.backend.metrics import ( # noqa: PLC0415 — keep prometheus deps off the api import path
observe_prewarmed_activated,
)
if description and not (task.description or "").strip():
task.description = description
task.save(update_fields=["description", "updated_at"])
activation_state_updates: dict[str, object] = {"pr_base_branch": branch}
if auto_publish is not None:
# Before the signal: the agent-server re-reads run state when the forwarded
# first message arrives, so the choice must already be persisted by then.
activation_state_updates["auto_publish"] = auto_publish
if reasoning_effort is not None:
activation_state_updates["reasoning_effort"] = reasoning_effort
TaskRun.update_state_atomic(
run.id,
updates=activation_state_updates,
remove_keys=["reasoning_effort"] if reasoning_effort is None else None,
)
_deliver_warm_run_message(
run, message=message, artifact_ids=artifact_ids, message_id=_warm_retry_message_id(retry_token, run)
)
# Only count activations of Runs that actually carry the prewarmed marker, so the activation
# numerator stays consistent with the workflow_start{prewarmed="true"} denominator — otherwise
# warm Runs provisioned before this ships (await_user_message set, prewarmed absent) would push
# the hit rate above 1 during the deploy transition.
if (run.state or {}).get("prewarmed"):
observe_prewarmed_activated(run)
def _team_github_integration_or_none(team_id: int, integration_id: int) -> IntegrationRecord | None:
try:
return IntegrationManager.github.oauth.get(team_id, integration_id)
except IntegrationNotFound:
return None
def _report_task_github_integration_id(team: Team, *, code_access_allowed: bool) -> int | None:
if not code_access_allowed:
return None
from products.signals.backend.facade.github_optional import (
github_optional_pilot_enabled, # noqa: PLC0415 - keeps the signals model graph out of tasks facade initialization
)
if github_optional_pilot_enabled(team.id):
return readonly_github_integration_id(team.id)
integration = IntegrationManager.github.oauth.find(team.id)
return integration.id if integration is not None else None
def _reserve_report_warm_activation(
team: Team, task: Task, *, relationship: str | None, description: str | None = None
) -> str:
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product write kept off the api import path
enforce_report_task_cap,
is_pull_request_run_request,
record_report_task,
)
report_id = str(task.signal_report_source_id)
if is_pull_request_run_request(description):
enforce_self_driving_free_trial(team, report_id=report_id)
with transaction.atomic():
enforce_report_task_cap(
team_id=task.team_id,
report_id=report_id,
relationship=relationship,
description=description,
created_by_id=task.created_by_id,
)
return record_report_task(
team_id=task.team_id, report_id=report_id, task_id=str(task.id), relationship=relationship
)
def _is_unlinked_report_warm_task(task: Task) -> bool:
if task.origin_product != Task.OriginProduct.SIGNAL_REPORT or not task.signal_report_source_id:
return False
if not task.runs.filter(team_id=task.team_id, state__has_key="prewarmed").exists():
return False
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product read kept off the api import path
report_task_ids,
)
return str(task.id) not in report_task_ids(team_id=task.team_id, report_id=str(task.signal_report_source_id))
def task_run_awaits_report_activation(run_id: str | UUID, task_id: str | UUID, team_id: int) -> bool:
run = _get_visible_run(run_id, task_id, team_id)
return run is not None and _is_unlinked_report_warm_task(run.task)
def warm_task_sandbox(
team_id: int,
user_id: int,
*,
repository: str | None,
repositories: list[str] | None = None,
github_integration_id: int | None,
branch: str | None,
runtime_adapter: str | None = None,
model: str | None = None,
reasoning_effort: str | None = None,
sandbox_environment_id: str | UUID | None = None,
custom_image_id: str | UUID | None = None,
client_provenance: TaskClientProvenance | None = None,
origin_product: str = Task.OriginProduct.USER_CREATED,
initial_permission_mode: str | None = None,
signal_report_id: str | UUID | None = None,
code_access_allowed: bool = False,
) -> contracts.WarmTaskDTO | None:
"""Warm a full idling Run for a cloud task while the user composes.
``origin_product`` is stamped on the draft Task and fixes what the warm can later be reused for: it
selects the OAuth app, the warm quota gate (``USER_CREATED`` has no billing gate; ``POSTHOG_AI`` runs
the AI-credit check), the warm-pool caps, and PR authorship. None of these can change at activation,
so a submit only reuses a warm born under the same origin. Defaults to ``USER_CREATED`` for the
Code-app callers that predate the parameter.
Births a draft Task, then ``SandboxWarmer.warm()`` provisions an interactive
Run that boots, optionally clones and checks out ``branch``, then starts the agent on the selected
``runtime_adapter``/``model``/``reasoning_effort`` (carried on the Run state and read by the
agent-server at launch, so the sandbox boots on the right runtime), then idles awaiting the first
``user_message``. The Run is dispatched with ``create_pr=True`` so that, once activated on submit,
it completes autonomously and opens a PR like a normal Code-app cloud task.
Best-effort: returns ``None`` (not an HTTP error) when warming is gated — over quota
(``QuotaLimitExceeded``), product not enabled (``PermissionDenied``), or the warm pool is full
(``Throttled``). The caller treats ``None`` as "no warm run; fall through to a cold create+run".
When present, ``github_integration_id`` must already be re-scoped to ``team_id`` by the caller
(see :func:`resolve_team_github_integration_id`). A repository requires it; a repository-less warm
may carry it so the Run boots with the same GitHub credentials a repo-less create would get.
"""
from rest_framework.exceptions import ( # noqa: PLC0415 — keep DRF exception types off the api import path
PermissionDenied,
Throttled,
)
from posthog.exceptions import QuotaLimitExceeded # noqa: PLC0415 — keep billing deps off the api import path
from posthog.models import Team # noqa: PLC0415
from products.tasks.backend.logic.services.warm import (
SandboxWarmer, # noqa: PLC0415 — keep warming deps off the api import path
)
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
PrAuthorshipMode,
RunSource,
RuntimeAdapter,
get_provider_for_runtime_adapter,
)
team = Team.objects.get(id=team_id)
normalized_repositories = [repo.lower() for repo in (repositories or ([repository] if repository else []))]
repository = normalized_repositories[0] if normalized_repositories else None
if signal_report_id is not None:
normalized_repositories = []
repository = None
github_integration_id = _report_task_github_integration_id(team, code_access_allowed=code_access_allowed)
github_integration = None
if github_integration_id is not None:
try:
github_integration = IntegrationManager.github.oauth.get(team_id, github_integration_id)
except IntegrationNotFound:
github_integration = None
# An integration id that does not resolve to this team's GitHub integration is never warmed on, and
# a repository cannot be cloned without one. An integration without a repository is fine: the
# create path stores that pair too, and reuse matches on the integration id.
if github_integration_id is not None and github_integration is None:
return None
if normalized_repositories and github_integration is None:
return None
sandbox_environment = None
if sandbox_environment_id is not None:
sandbox_environment = SandboxEnvironment.get_accessible_for_task(
environment_id=sandbox_environment_id,
team_id=team_id,
task_created_by_id=user_id,
)
if sandbox_environment is None:
return None
custom_image = None
if custom_image_id is not None:
custom_image = SandboxCustomImage.get_accessible_for_task(
image_id=custom_image_id,
team_id=team_id,
task_created_by_id=user_id,
)
if custom_image is None or not custom_image.is_ready:
return None
# Resolve team/user defaults up front so the warm run is provisioned (and later
# matched) on the runtime the activating submit will effectively request.
warm_selection = _with_ai_run_defaults(
{"runtime_adapter": runtime_adapter, "model": model, "reasoning_effort": reasoning_effort},
team_id=team_id,
acting_user_id=user_id,
)
runtime_adapter = warm_selection.get("runtime_adapter")
model = warm_selection.get("model")
reasoning_effort = warm_selection.get("reasoning_effort")
existing = _find_idling_warm_run(
team_id,
user_id,
origin_product=origin_product,
repository=repository,
repositories=normalized_repositories,
github_integration_id=github_integration_id,
branch=branch,
runtime_adapter=runtime_adapter,
model=model,
reasoning_effort=reasoning_effort,
sandbox_environment_id=sandbox_environment_id,
custom_image_id=custom_image_id,
initial_permission_mode=initial_permission_mode,
signal_report_id=signal_report_id,
)
if existing is not None:
return contracts.WarmTaskDTO(task_id=existing.task_id, run_id=existing.id)
task = Task.create_without_run(
team=team,
title="",
description="",
origin_product=Task.OriginProduct(origin_product),
user_id=user_id,
repositories=normalized_repositories,
signal_report_id=str(signal_report_id) if signal_report_id is not None else None,
client_provenance=client_provenance,
)
# `_build_task` resolves the team's first GitHub integration; a warm must instead hold the
# one the caller asked for, because warm reuse matches on the integration id.
task.github_integration_id = github_integration.id if github_integration is not None else None
task.save(update_fields=["github_integration", "updated_at"])
assert task.created_by is not None # create_without_run always sets created_by from user_id
provider = get_provider_for_runtime_adapter(runtime_adapter)
# The agent session is constructed with this mode at boot and it cannot be changed once the sandbox
# is warm, so an explicit request wins and reuse matches on it. Callers that omit it (the Code app)
# keep the runtime-derived default they have always had.
resolved_permission_mode = initial_permission_mode or (
"auto" if runtime_adapter == RuntimeAdapter.CODEX.value else "default"
)
extra_state: dict = {
"branch": branch,
"pr_base_branch": branch,
"initial_permission_mode": resolved_permission_mode,
}
if sandbox_environment is not None:
extra_state["sandbox_environment_id"] = str(sandbox_environment.id)
if custom_image is not None:
extra_state["custom_image_id"] = str(custom_image.id)
if signal_report_id is not None:
extra_state["run_source"] = RunSource.SIGNAL_REPORT.value
extra_state["signal_report_id"] = str(signal_report_id)
extra_state["pr_authorship_mode"] = PrAuthorshipMode.BOT.value
for key, value in {
"runtime_adapter": runtime_adapter,
"provider": provider.value if provider is not None else None,
"model": model,
"reasoning_effort": reasoning_effort,
}.items():
if value is not None:
extra_state[key] = value
try:
result = SandboxWarmer(task, user=task.created_by).warm(
mode="interactive",
extra_state=extra_state,
create_pr=True,
)
except (Throttled, PermissionDenied, QuotaLimitExceeded):
task.soft_delete()
return None
return contracts.WarmTaskDTO(task_id=task.id, run_id=result.run.id)
def warm_task_resume_sandbox(
task_id: str | UUID,
team_id: int,
user_id: int,
*,
resume_from_run_id: str | UUID,
runtime_adapter: str | None = None,
model: str | None = None,
reasoning_effort: str | None = None,
initial_permission_mode: str | None = None,
) -> contracts.WarmTaskDTO | None:
"""Warm a successor for the task's current terminal run while its next message is composed."""
from rest_framework.exceptions import ( # noqa: PLC0415 — keep DRF exception types off the api import path
PermissionDenied,
Throttled,
)
from posthog.exceptions import QuotaLimitExceeded # noqa: PLC0415 — keep billing deps off the api import path
from products.tasks.backend.logic.services.warm import ( # noqa: PLC0415 — keep warming deps off the api import path
SandboxWarmer,
WarmSourceChanged,
)
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
RunSource,
get_pr_authorship_mode,
get_provider_for_runtime_adapter,
get_reasoning_effort_error,
parse_run_state,
)
task = _visible_task_qs(team_id, user_id, for_control=True).select_related("team").filter(id=task_id).first()
if task is None or not _task_drive_allowed(task, user_id):
return None
previous_run = task.runs.filter(id=resume_from_run_id).first()
if previous_run is None or not previous_run.is_terminal:
return None
if not previous_run.matches_task_ownership(task):
# A handed-off task keeps its old runs stamped with the previous owner, so create_run would
# reject this resume source with TaskOwnershipChangedError. Skip warming; the cold resume path
# reports the friendly error when the person submits.
return None
latest_run = task.latest_run
latest_state = (latest_run.state or {}) if latest_run is not None else {}
latest_is_expected_source = latest_run is not None and latest_run.id == previous_run.id
latest_is_expected_warm = (
latest_run is not None
and not latest_run.is_terminal
and latest_state.get("await_user_message") is True
and latest_state.get("resume_from_run_id") == str(previous_run.id)
)
# A successor the composer handed back (or the reaper took) is terminal and sits in front of its
# own source, so neither test above sees it. Without this the first release would leave the task
# unable to warm again until it was submitted — and releases are routine: an emptied draft, a
# changed model or mode, or leaving the composer. The source fence still holds, because the
# released successor has to have been warmed for this same run.
latest_is_released_warm = (
latest_run is not None
and latest_run.is_terminal
and latest_state.get("prewarmed") is True
and latest_state.get("await_user_message") is True
and latest_state.get("resume_from_run_id") == str(previous_run.id)
)
if not latest_is_expected_source and not latest_is_expected_warm and not latest_is_released_warm:
return None
previous_state = parse_run_state(previous_run.state)
if previous_state.run_source == RunSource.AGENT or previous_state.model_access.kind == "own-subscription":
return None
resolved_runtime_adapter = runtime_adapter or previous_state.runtime_adapter
resolved_model = model or previous_state.model
resolved_reasoning_effort = reasoning_effort or previous_state.reasoning_effort
resolved_permission_mode = initial_permission_mode or previous_state.initial_permission_mode or "default"
reasoning_effort_error = get_reasoning_effort_error(
runtime_adapter=resolved_runtime_adapter,
model=resolved_model,
reasoning_effort=resolved_reasoning_effort,
)
if reasoning_effort_error is not None:
return None
user = User.objects.get(pk=user_id)
model_access_error = get_model_access_error(resolved_model, distinct_id=user.distinct_id)
if model_access_error is not None:
return None
resolved_pr_authorship_mode, validation_error = _resolve_cloud_pr_authorship_mode(
task,
pr_authorship_mode=get_pr_authorship_mode(task, previous_run.state),
request_user_id=user_id,
github_user_token=None,
)
if validation_error is not None:
return None
branch = previous_state.pr_base_branch
sandbox_environment_id = previous_state.sandbox_environment_id
custom_image_id = (previous_run.state or {}).get("custom_image_id")
if not _warm_sandbox_selection_is_accessible(
team_id=team_id,
task_created_by_id=task.created_by_id,
sandbox_environment_id=sandbox_environment_id,
custom_image_id=custom_image_id,
):
return None
def state_value(value: object | None) -> object | None:
return value.value if hasattr(value, "value") else value
extra_state: dict[str, Any] = {
"branch": branch,
"pr_base_branch": branch,
"pr_authorship_mode": state_value(resolved_pr_authorship_mode),
"auto_publish": previous_state.auto_publish,
"run_source": state_value(previous_state.run_source),
"signal_report_id": previous_state.signal_report_id,
"runtime_adapter": state_value(resolved_runtime_adapter),
"provider": state_value(get_provider_for_runtime_adapter(resolved_runtime_adapter)),
"model": resolved_model,
"reasoning_effort": state_value(resolved_reasoning_effort),
"context_window": previous_state.context_window,
"fast_mode": previous_state.fast_mode,
"initial_permission_mode": state_value(resolved_permission_mode),
"sandbox_environment_id": sandbox_environment_id,
"custom_image_id": custom_image_id,
}
extra_state.update(_github_credential_source_extra_state(resolved_pr_authorship_mode, None))
for protected_key in (
"wizard_head_branch",
"self_driving_head_branch",
"stack_base_branch",
"github_read_access",
"github_token_scope",
"github_access_repositories",
):
if protected_key in (previous_run.state or {}):
extra_state[protected_key] = (previous_run.state or {})[protected_key]
if "imported_from" in (previous_run.state or {}):
extra_state["resume_from_import_run"] = True
extra_state = {key: value for key, value in extra_state.items() if value is not None or key == "pr_base_branch"}
stable_selection = {
key: value
for key, value in extra_state.items()
if key
in {
"branch",
"runtime_adapter",
"model",
"context_window",
"fast_mode",
"initial_permission_mode",
"sandbox_environment_id",
"custom_image_id",
"pr_authorship_mode",
"github_credential_source",
}
}
try:
result = SandboxWarmer(task, user=user).warm(
mode="interactive",
extra_state=extra_state,
create_pr=True,
expected_resume_from_run_id=previous_run.id,
required_existing_state=stable_selection,
)
except (PermissionDenied, QuotaLimitExceeded, Throttled, WarmSourceChanged, TaskOwnershipChangedError):
# TaskOwnershipChangedError guards a handoff that lands after the check above but before the
# locked create_run, keeping this best-effort endpoint from returning a server error.
return None
return contracts.WarmTaskDTO(task_id=task.id, run_id=result.run.id)
# --- Task run (the ``run`` action) ---
def _branches_worked_on(run: TaskRun) -> set[str]:
output = run.output if isinstance(run.output, dict) else {}
branches = {entry["branch"] for entry in read_head_branches(output)}
head_branch = output.get("head_branch")
if isinstance(head_branch, str) and head_branch:
branches.add(head_branch)
if run.branch:
branches.add(run.branch)
return branches
def _active_session_cap_refusal(task: Task) -> str | None:
from products.tasks.backend.logic.services.warm import (
SandboxWarmer, # noqa: PLC0415 — keep warming deps off the api import path
)
from products.tasks.backend.metrics import (
observe_active_session_cap_hit, # noqa: PLC0415 — keep prometheus deps off the api import path
)
scope = SandboxWarmer.active_session_cap_hit(
task.origin_product,
organization_id=task.team.organization_id,
created_by_id=task.created_by_id,
signal_report_id=task.signal_report_id,
task_id=task.id,
)
if scope is None:
return None
observe_active_session_cap_hit(task.origin_product, scope)
return SandboxWarmer.active_session_cap_detail(task.origin_product, scope, signal_report_id=task.signal_report_id)
def run_task(
task_id: str | UUID,
team_id: int,
user_id: int | None,
*,
validated_data: dict,
warm_retry_token: str | None = None,
pipeline_rerun: bool = False,
free_trial_enabled: bool | None = None,
) -> contracts.TaskRunResult | None:
"""Return None for an inaccessible task, otherwise return its refreshed detail or a structured error.
The caller applies the usage gate. Only server-requested Signals research may set pipeline_rerun.
"""
from products.signals.backend.facade.report_tasks import ( # noqa: PLC0415 — cross-product read kept off the api import path
enforce_report_implementation_rerun_cap,
is_report_implementation_task,
)
from products.tasks.backend.logic.services.staged_artifacts import ( # noqa: PLC0415
RUN_ARTIFACT_TTL_DAYS,
get_task_run_artifacts_by_id,
get_task_staged_artifacts,
staged_artifacts_expire_by,
tag_task_artifact,
)
from products.tasks.backend.temporal.process_task.utils import ( # noqa: PLC0415 — keep temporalio off the api import path
PrAuthorshipMode,
RunSource,
cache_github_user_token,
get_provider_for_runtime_adapter,
get_reasoning_effort_error,
mcp_scopes_for_run_source,
parse_run_state,
)
task = _visible_task_qs(team_id, user_id, for_control=True).filter(id=task_id).first()
if task is None:
return None
# Another product may need to finish something before this task runs, for example a chat that
# is copied into the task a few seconds behind each turn.
refusal = task_run_start_refusal(str(task.id), team_id, user_id)
if refusal is not None:
return contracts.TaskRunResult(error=contracts.TaskValidationError(kind="detail", detail=refusal))
if _is_unlinked_report_warm_task(task):
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail=REPORT_WARM_RUN_NOT_ACTIVATED)
)
if not validated_data.get("scheduled_at"):
cap_detail = _active_session_cap_refusal(task)
if cap_detail is not None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail=cap_detail, code=ACTIVE_SESSION_CAP_CODE)
)
report_id_for_slot_check = (
str(task.signal_report_source_id)
if task.signal_report_source_id and task.origin_product == Task.OriginProduct.SIGNAL_REPORT
else None
)
is_implementation = False
if report_id_for_slot_check is not None:
# Resolve the trial flag outside the transaction: network I/O must not hold the report lock.
is_implementation = is_report_implementation_task(
team_id=team_id, report_id=report_id_for_slot_check, task_id=str(task.id)
)
if is_implementation:
enforce_self_driving_free_trial(
Team.objects.select_related("organization").get(id=team_id),
report_id=report_id_for_slot_check,
stage="task_run",
enabled=free_trial_enabled,
)
# Ahead of the warm-run reuse below, which returns early: a task released its slot when
# its runs all failed, so another implementation may hold it by now. Refusing here also
# avoids the sandbox and repository lookups a doomed run would otherwise do first. The
# check that actually holds the slot is the one wrapping `create_run` below.
with transaction.atomic():
enforce_report_implementation_rerun_cap(
team_id=team_id, report_id=report_id_for_slot_check, task_id=str(task.id)
)
mode = validated_data.get("mode", "background")
run_source = validated_data.get("run_source")
scheduled_at = validated_data.get("scheduled_at")
branch = validated_data.get("branch")
resume_from_run_id = validated_data.get("resume_from_run_id")
pending_user_message = validated_data.get("pending_user_message")
pending_user_artifact_ids = validated_data.get("pending_user_artifact_ids") or []
is_pi_task = task.runtime == Task.Runtime.PI
previous_run: TaskRun | None = None
previous_state = None
previous_is_import_run = False
if resume_from_run_id:
previous_run = task.runs.filter(id=resume_from_run_id).first()
if previous_run is None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail="Invalid resume_from_run_id")
)
previous_is_import_run = "imported_from" in (previous_run.state or {})
if not previous_run.matches_task_ownership(task):
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="detail",
detail="This run belongs to a previous task owner. Start a new run instead.",
)
)
previous_state = parse_run_state(previous_run.state)
if previous_state.run_source == RunSource.AGENT:
run_source = RunSource.AGENT
previous_branch = previous_state.pr_base_branch
if branch is not None and branch != previous_branch and branch not in _branches_worked_on(previous_run):
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="detail", detail="A resumed run must use its previous base branch. Omit branch to resume."
)
)
branch = previous_branch
if branch is None and not resume_from_run_id and task.origin_product == Task.OriginProduct.SIGNAL_REPORT:
# The inbox "Create PR" button sends no branch, so without this the run would target the
# repository's GitHub default branch. Auto-start resolves the same setting when it builds
# its task. This sits before the warm-run reuse check below, so that a sandbox idling on
# the default branch is not reused for a run that needs the configured branch.
from products.signals.backend.facade.api import ( # noqa: PLC0415 — cross-product read kept off the api import path
autostart_base_branch_for_repository,
)
branch = autostart_base_branch_for_repository(
team_id, task.repositories[0] if task.repositories else task.repository
)
if not resume_from_run_id or previous_is_import_run:
# Fill team/user default AI run preferences before warm matching: a warm run
# provisioned under the default triple must still match a submit that pinned
# nothing. Resumes instead carry the previous run's selection (below), except from
# an import run, which never ran and so pins no selection to carry.
validated_data = _with_ai_run_defaults(
validated_data,
team_id=task.team_id,
acting_user_id=user_id if user_id is not None else task.created_by_id,
internal=task.internal,
runtime=task.runtime,
)
access_state = {
**(previous_state.model_dump() if previous_state is not None else {}),
**{key: value for key, value in validated_data.items() if value is not None},
}
try:
model_access = resolve_model_access(access_state)
except ValueError as error:
return contracts.TaskRunResult(error=contracts.TaskValidationError(kind="detail", detail=str(error)))
claude_model_access = model_access.access_for("claude") if "claude_model_access" in access_state else None
codex_model_access = model_access.access_for("codex") if "codex_model_access" in access_state else None
if scheduled_at is not None and model_access.kind == "own-subscription":
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="validation_error",
code="invalid_input",
detail="Scheduled runs must use the PostHog gateway.",
attr="codex_model_access" if codex_model_access == "own-subscription" else "claude_model_access",
)
)
warm_run = (
None
if pipeline_rerun
or scheduled_at is not None
or run_source == RunSource.AGENT
or validated_data.get("client_platform") == "mobile"
else _idling_warm_run_for_task(task)
)
# A warm sandbox was started before the plan choice, so it holds no run-scoped subscription token.
if warm_run is not None and model_access.kind == "own-subscription":
warm_run = None
if warm_run is not None:
_warm_retry_message_id(warm_retry_token, warm_run)
warm_state = warm_run.state or {}
# Both directions. A request that states no resume source must not be handed a successor
# warmed to resume an earlier run — its filesystem was restored from that run's snapshot, so
# a run asked to start fresh would silently inherit it.
warm_resume_matches = (warm_state.get("resume_from_run_id") or None) == (
str(resume_from_run_id) if resume_from_run_id else None
)
if warm_resume_matches and (branch or None) == (warm_run.branch or None):
desired_runtime_adapter = validated_data.get("runtime_adapter")
desired_model = validated_data.get("model")
desired_context_window = validated_data.get("context_window")
desired_fast_mode = validated_data.get("fast_mode")
desired_sandbox_environment_id = validated_data.get("sandbox_environment_id")
desired_custom_image_id = validated_data.get("custom_image_id")
if previous_state is not None:
assert previous_run is not None
desired_runtime_adapter = desired_runtime_adapter or previous_state.runtime_adapter
desired_model = desired_model or previous_state.model
desired_context_window = desired_context_window or previous_state.context_window
if desired_fast_mode is None:
desired_fast_mode = previous_state.fast_mode
desired_sandbox_environment_id = desired_sandbox_environment_id or previous_state.sandbox_environment_id
desired_custom_image_id = desired_custom_image_id or (previous_run.state or {}).get("custom_image_id")
def state_value(value: object | None) -> object | None:
return value.value if hasattr(value, "value") else value
warm_runtime_matches = (
warm_state.get("runtime_adapter") or None,
warm_state.get("model") or None,
warm_state.get("context_window") or None,
warm_state.get("fast_mode") or None,
warm_state.get("sandbox_environment_id") or None,
warm_state.get("custom_image_id") or None,
) == (
state_value(desired_runtime_adapter) or None,
desired_model or None,
desired_context_window or None,
desired_fast_mode or None,
str(desired_sandbox_environment_id) if desired_sandbox_environment_id else None,
str(desired_custom_image_id) if desired_custom_image_id else None,
)
requested_permission_mode = validated_data.get("initial_permission_mode")
if previous_state is not None:
requested_permission_mode = (
requested_permission_mode or previous_state.initial_permission_mode or "default"
)
warm_permission_matches = requested_permission_mode is None or warm_state.get(
"initial_permission_mode"
) == state_value(requested_permission_mode)
if (
warm_runtime_matches
and warm_permission_matches
and _warm_sandbox_selection_is_accessible(
team_id=team_id,
task_created_by_id=task.created_by_id,
sandbox_environment_id=warm_state.get("sandbox_environment_id"),
custom_image_id=warm_state.get("custom_image_id"),
)
):
warm_staged_artifacts, warm_missing_artifact_ids = (
get_task_staged_artifacts(task, pending_user_artifact_ids)
if pending_user_artifact_ids
else ([], [])
)
if warm_missing_artifact_ids:
# A previous activation attempt may have moved these out of staging before delivery failed.
_, warm_missing_artifact_ids = get_task_run_artifacts_by_id(warm_run, warm_missing_artifact_ids)
if not warm_missing_artifact_ids:
if warm_staged_artifacts:
_attach_staged_artifacts_to_run(
warm_run,
task,
staged_artifacts=warm_staged_artifacts,
artifact_ids=pending_user_artifact_ids,
)
_activate_warm_run(
warm_run,
task,
team_id,
message=pending_user_message or (task.description or None),
branch=branch,
description=task.description or None,
artifact_ids=pending_user_artifact_ids,
auto_publish=validated_data.get("auto_publish"),
reasoning_effort=validated_data.get("reasoning_effort"),
retry_token=warm_retry_token,
)
return contracts.TaskRunResult(task=get_task_detail(task.id, team_id, user_id), run_id=warm_run.id)
if warm_retry_token is not None:
raise WarmRunActivationUnavailable("target_unavailable")
sandbox_environment_id = validated_data.get("sandbox_environment_id")
sandbox_environment_id_supplied_by_user = sandbox_environment_id is not None
custom_image_id = validated_data.get("custom_image_id")
custom_image_id_supplied_by_user = custom_image_id is not None
pr_authorship_mode = validated_data.get("pr_authorship_mode")
auto_publish = validated_data.get("auto_publish")
signal_report_id = validated_data.get("signal_report_id")
runtime_adapter = validated_data.get("runtime_adapter")
model = validated_data.get("model")
reasoning_effort = validated_data.get("reasoning_effort")
context_window = validated_data.get("context_window")
fast_mode = validated_data.get("fast_mode")
github_user_token = validated_data.get("github_user_token")
initial_permission_mode = validated_data.get("initial_permission_mode")
imported_mcp_servers = validated_data.get("imported_mcp_servers")
relayed_mcp_servers = validated_data.get("relayed_mcp_servers")
if run_source == RunSource.SIGNAL_REPORT:
pr_authorship_mode = PrAuthorshipMode.BOT
runtime_state_fields = {
**_task_run_runtime_state_fields(validated_data),
"pr_authorship_mode": pr_authorship_mode,
"run_source": run_source,
}
extra_state: dict | None = None
if pending_user_message is not None and not is_pi_task:
extra_state = {"pending_user_message": pending_user_message}
if pending_user_artifact_ids and not is_pi_task:
extra_state = extra_state or {}
extra_state["pending_user_artifact_ids"] = pending_user_artifact_ids
for key, value in (
("client_platform", validated_data.get("client_platform")),
("initial_permission_mode", initial_permission_mode),
("rtk_enabled", validated_data.get("rtk_enabled")),
("benjamin_enabled", validated_data.get("benjamin_enabled")),
("claude_model_access", claude_model_access),
("codex_model_access", codex_model_access),
("agent_parent_task_id", validated_data.get("agent_parent_task_id")),
("agent_parent_run_id", validated_data.get("agent_parent_run_id")),
):
if value is not None:
extra_state = extra_state or {}
extra_state[key] = value
if resume_from_run_id:
assert previous_run is not None and previous_state is not None
prev_state = previous_state
extra_state = extra_state or {}
if not extra_state.get("client_platform") and (previous_run.state or {}).get("client_platform") == "mobile":
extra_state["client_platform"] = "mobile"
if previous_run.task_summary:
extra_state[PRIOR_RUN_SUMMARY_STATE_KEY] = previous_run.task_summary
if previous_run.task_tags:
extra_state[PRIOR_RUN_TAGS_STATE_KEY] = previous_run.task_tags
if not is_pi_task:
extra_state["resume_from_run_id"] = str(resume_from_run_id)
extra_state.update(prev_state.resume_snapshot_carry_state())
if previous_is_import_run:
extra_state["resume_from_import_run"] = True
# The resumed agent still pushes the head branch baked into the original prompt, so the
# PR webhook must be able to match this run, not the terminal predecessor.
prev_wizard_head_branch = (previous_run.state or {}).get("wizard_head_branch")
if prev_wizard_head_branch:
extra_state["wizard_head_branch"] = prev_wizard_head_branch
# Same reasoning for a signals self-driving run: the head branch is baked into the original
# prompt, so the resumed run pushes it too, and the review carve-out's branch linkage
# (find_signal_implementation_run) only matches the successor if its stamp is carried
# forward — otherwise a resume (the usual recovery for a cancelled run) silently ends
# re-reviews. The key is PATCH-protected, so this server-side copy is the only way it
# reaches the successor run.
prev_self_driving_head_branch = (previous_run.state or {}).get("self_driving_head_branch")
if prev_self_driving_head_branch:
extra_state["self_driving_head_branch"] = prev_self_driving_head_branch
# The launch protects the stacked base only while the run is still on that exact branch, so
# carrying the marker is safe once the run moved to its own head branch.
prev_stack_base_branch = (previous_run.state or {}).get("stack_base_branch")
if prev_stack_base_branch:
extra_state["stack_base_branch"] = prev_stack_base_branch
# The resumed agent still works with the repositories it was told about, so its token must
# keep covering them. The key is PATCH-protected, so this copy is the only way it carries.
prev_github_access_repositories = (previous_run.state or {}).get("github_access_repositories")
if prev_github_access_repositories:
extra_state["github_access_repositories"] = prev_github_access_repositories
if pipeline_rerun and is_implementation:
extra_state["ai_stage"] = "implementation"
# A read-only GitHub grant describes how the task was created, not one run — without the
# carry-forward, a resumed successor of a repo-less read-only run falls through to the
# full credential path and regains the write-capable token. (The key is PATCH-protected,
# so this server-side copy is the only way it reaches a successor run.)
if (previous_run.state or {}).get("github_read_access") is True:
extra_state["github_read_access"] = True
if github_token_scope := (previous_run.state or {}).get("github_token_scope"):
extra_state["github_token_scope"] = github_token_scope
# A resumed child run stays a child, so its sandbox still cannot start more runs. The keys
# are PATCH-protected, so this server-side copy is the only way they reach a successor run.
for lineage_key in ("agent_parent_task_id", "agent_parent_run_id"):
if lineage_key not in extra_state and (lineage_value := (previous_run.state or {}).get(lineage_key)):
extra_state[lineage_key] = lineage_value
if prev_state.sandbox_environment_id and sandbox_environment_id is None:
sandbox_environment_id = prev_state.sandbox_environment_id
if custom_image_id is None:
custom_image_id = (previous_run.state or {}).get("custom_image_id")
for field_name in runtime_state_fields:
if runtime_state_fields[field_name] is None:
runtime_state_fields[field_name] = getattr(prev_state, field_name)
pr_authorship_mode = runtime_state_fields["pr_authorship_mode"]
auto_publish = runtime_state_fields["auto_publish"]
run_source = runtime_state_fields["run_source"]
signal_report_id = runtime_state_fields["signal_report_id"]
runtime_adapter = runtime_state_fields["runtime_adapter"]
model = runtime_state_fields["model"]
reasoning_effort = runtime_state_fields["reasoning_effort"]
context_window = runtime_state_fields["context_window"]
fast_mode = runtime_state_fields["fast_mode"]
provider = get_provider_for_runtime_adapter(runtime_adapter)
run_state_values = {
"pr_authorship_mode": pr_authorship_mode,
"auto_publish": auto_publish,
"run_source": run_source,
"signal_report_id": signal_report_id,
"runtime_adapter": runtime_adapter,
"provider": provider,
"model": model,
"reasoning_effort": reasoning_effort,
"context_window": context_window,
"fast_mode": fast_mode,
}
if is_pi_task:
run_state_values.pop("runtime_adapter")
run_state_values.pop("provider")
extra_state = extra_state or {}
extra_state["pr_base_branch"] = branch
for key, value in run_state_values.items():
if value is not None:
extra_state[key] = value.value if hasattr(value, "value") else value
reasoning_effort_error = get_reasoning_effort_error(
runtime_adapter=runtime_adapter, model=model, reasoning_effort=reasoning_effort
)
if reasoning_effort_error is not None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="validation_error", code="invalid_input", detail=reasoning_effort_error, attr="reasoning_effort"
)
)
# A resume inherits the previous run's model, so the serializer's check saw `None` and
# passed. Re-check the model that will actually run. Only a gated model pays the lookup.
if get_required_model_flag(model) is not None:
actor_distinct_id = (
User.objects.filter(pk=user_id).values_list("distinct_id", flat=True).first() if user_id else None
)
model_access_error = get_model_access_error(model, distinct_id=actor_distinct_id)
if model_access_error is not None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="validation_error", code="invalid_input", detail=model_access_error, attr="model"
)
)
pr_authorship_mode, validation_error = _resolve_cloud_pr_authorship_mode(
task,
pr_authorship_mode=pr_authorship_mode,
request_user_id=user_id,
github_user_token=github_user_token,
)
if validation_error is not None:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind=validation_error.kind,
detail=validation_error.detail,
code=validation_error.code,
attr=validation_error.attr,
)
)
if pr_authorship_mode is not None:
extra_state = extra_state or {}
extra_state["pr_authorship_mode"] = (
pr_authorship_mode.value if hasattr(pr_authorship_mode, "value") else pr_authorship_mode
)
if credential_source := _github_credential_source_extra_state(pr_authorship_mode, github_user_token):
extra_state = extra_state or {}
extra_state.update(credential_source)
if custom_image_id is not None:
custom_image = SandboxCustomImage.get_accessible_for_task(
image_id=custom_image_id, team_id=task.team_id, task_created_by_id=task.created_by_id
)
if custom_image is None:
if custom_image_id_supplied_by_user:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail="Invalid custom_image_id")
)
elif not custom_image.is_ready:
if custom_image_id_supplied_by_user:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="detail", detail=f"Custom image is not ready (status: {custom_image.status})"
)
)
else:
extra_state = extra_state or {}
extra_state["custom_image_id"] = str(custom_image.id)
if sandbox_environment_id is not None:
sandbox_environment = SandboxEnvironment.get_accessible_for_task(
environment_id=sandbox_environment_id,
team_id=task.team_id,
task_created_by_id=task.created_by_id,
)
if sandbox_environment is None:
if sandbox_environment_id_supplied_by_user:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(kind="detail", detail="Invalid sandbox_environment_id")
)
else:
extra_state = extra_state or {}
extra_state["sandbox_environment_id"] = str(sandbox_environment.id)
logger.info(
"Applying sandbox environment to task run",
extra={
"task_id": str(task.id),
"sandbox_environment_id": str(sandbox_environment.id),
"sandbox_environment_name": sandbox_environment.name,
"network_access_level": sandbox_environment.network_access_level,
},
)
staged_artifacts: list[dict] = []
if pending_user_artifact_ids:
staged_artifacts, missing_artifact_ids = get_task_staged_artifacts(task, pending_user_artifact_ids)
if missing_artifact_ids:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="detail",
detail="Some pending_user_artifact_ids are invalid or expired",
missing_artifact_ids=missing_artifact_ids,
)
)
if scheduled_at is not None and staged_artifacts_expire_by(staged_artifacts, scheduled_at):
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="validation_error",
code="invalid_input",
detail="The attached files expire before this run can start. Choose an earlier time or upload new files.",
attr="scheduled_at",
)
)
logger.info("Creating task run for task %s with mode=%s, branch=%s", task.id, mode, branch)
if scheduled_at is not None:
for staged_artifact in staged_artifacts:
tag_task_artifact(
str(staged_artifact["storage_path"]),
ttl_days=RUN_ARTIFACT_TTL_DAYS,
team_id=task.team_id,
raise_on_error=True,
)
extra_state["pending_dispatch"] = {
"user_id": user_id,
"create_pr": True,
"posthog_mcp_scopes": mcp_scopes_for_run_source(run_source),
}
try:
with transaction.atomic():
task_run = task.create_run(
mode=mode, branch=branch, extra_state=extra_state, acting_user_id=user_id, scheduled_at=scheduled_at
)
if report_id_for_slot_check is not None:
enforce_report_implementation_rerun_cap(
team_id=team_id, report_id=report_id_for_slot_check, task_id=str(task.id)
)
if scheduled_at is not None and pending_user_artifact_ids:
_attach_staged_artifacts_to_run(
task_run, task, staged_artifacts=staged_artifacts, artifact_ids=pending_user_artifact_ids
)
except InvalidTaskOriginError as error:
return contracts.TaskRunResult(
error=contracts.TaskValidationError(
kind="validation_error", code="invalid_input", detail=str(error), attr="origin_product"
)
)
except TaskOwnershipChangedError:
return None
if is_pi_task and resume_from_run_id:
assert previous_run is not None
task_run.active_task_session = previous_run.active_task_session
task_run.save(update_fields=["active_task_session", "updated_at"])
if imported_mcp_servers or relayed_mcp_servers:
update_fields = ["updated_at"]
if imported_mcp_servers:
# Kept out of `state` (a plain JSONField) because header values carry credentials.
task_run.imported_mcp_servers = imported_mcp_servers
update_fields.append("imported_mcp_servers")
if relayed_mcp_servers:
task_run.relayed_mcp_servers = relayed_mcp_servers
update_fields.append("relayed_mcp_servers")
task_run.save(update_fields=update_fields)
if pending_user_artifact_ids and scheduled_at is None:
_attach_staged_artifacts_to_run(
task_run, task, staged_artifacts=staged_artifacts, artifact_ids=pending_user_artifact_ids
)
if github_user_token and pr_authorship_mode == PrAuthorshipMode.USER:
cache_github_user_token(str(task_run.id), github_user_token)
if scheduled_at is not None:
return contracts.TaskRunResult(
task=_task_detail_to_dto(task, latest_run=task_run, include_latest_run_log_url=False),
run_id=task_run.id,
)
logger.info("Triggering workflow for task %s, run %s", task.id, task_run.id)
if is_pi_task:
initial_message = (
pending_user_message if resume_from_run_id else pending_user_message or task.description or None
)
run_error = _trigger_task_processing_workflow(
task,
task_run,
user_id,
initial_message=initial_message,
initial_artifact_ids=pending_user_artifact_ids,
raise_on_error=False,
)
else:
run_error = _trigger_task_processing_workflow(task, task_run, user_id, raise_on_error=False)
try:
if run_error is None:
task_run.refresh_from_db(fields=["status"])
if task_run.status == TaskRun.Status.FAILED:
run_error = WORKFLOW_START_FAILED_ERROR
task_detail = get_task_detail(task.id, team_id, user_id)
except Exception:
logger.exception("Failed to hydrate task %s after starting run %s", task.id, task_run.id)
task_detail = _task_detail_to_dto(task, latest_run=task_run, include_latest_run_log_url=False)
return contracts.TaskRunResult(task=task_detail, run_error=run_error, run_id=task_run.id)
# --- Task presence beacons ---
def beacon_task_presence(task_id: str | UUID, team_id: int, user_id: int | None, *, device_id) -> str:
"""Idempotent upsert of a presence row for a device watching a task.
Returns ``"not_found"`` (task not visible or device_id doesn't match the caller's push
token), or ``"ok"``. Mirrors ``TaskViewSet._presence_beacon``.
"""
from posthog.models.user_push_token import UserPushToken # noqa: PLC0415
from products.tasks.backend.models import TASK_PRESENCE_TTL_SECONDS, TaskPresence # noqa: PLC0415
if user_id is None:
return "not_found"
task = _visible_task_qs(team_id, user_id).filter(id=task_id).first()
if task is None:
return "not_found"
push_token = UserPushToken.objects.filter(user_id=user_id, id=device_id).first()
if push_token is None:
return "not_found"
now = django_timezone.now()
# nosemgrep: idor-lookup-without-team — team scope is enforced by TaskScopedManager
# and via the `task` FK whose row is fetched (visibility-gated) above.
TaskPresence.objects.update_or_create(
task=task,
push_token=push_token,
defaults={
"team": task.team,
"user_id": user_id,
"expires_at": now + timedelta(seconds=TASK_PRESENCE_TTL_SECONDS),
},
)
return "ok"
def leave_task_presence(task_id: str | UUID, team_id: int, user_id: int | None, *, device_id) -> str:
"""Best-effort delete of a presence row. ``"not_found"`` if the task isn't visible, else ``"ok"``.
No 404 on missing presence rows — leave runs from blur/background handlers. Mirrors
``TaskViewSet._presence_leave``.
"""
from products.tasks.backend.models import TaskPresence # noqa: PLC0415
if user_id is None:
return "not_found"
task = _visible_task_qs(team_id, user_id).filter(id=task_id).first()
if task is None:
return "not_found"
TaskPresence.objects.filter(task=task, push_token_id=device_id, user_id=user_id).delete()
return "ok"
# --- Slack thread context (internal debug) ---
def _temporal_workflow_url(workflow_id: str | None) -> str | None:
from django.conf import settings # noqa: PLC0415
if not workflow_id:
return None
base = getattr(settings, "TEMPORAL_UI_HOST", None)
namespace = getattr(settings, "TEMPORAL_NAMESPACE", None)
if not base or not namespace:
return None
return f"{base.rstrip('/')}/namespaces/{namespace}/workflows/{workflow_id}"
def _slack_queue_workflow_id(slack_workspace_id: str | None, channel: str, thread_ts: str) -> str | None:
"""The per-conversation queue workflow (`slack-app-mention-…`) that fronts every
per-message mention workflow. A message can stall or be deduped there before any
run exists, so the debug view links it at the thread level."""
from products.slack_app.backend.helpers import slack_app_mention_queue_workflow_id # noqa: PLC0415
if not slack_workspace_id:
return None
return slack_app_mention_queue_workflow_id(slack_workspace_id, channel, thread_ts)
def _admin_change_url(instance: Model, *, build_url) -> str:
"""Django admin change-page URL for a model row, built from the stable admin URL
layout instead of `reverse` — the admin URLconf is only mounted when
``ADMIN_PORTAL_ENABLED``, and this endpoint only serves PostHog Cloud US, where the
portal is always on."""
meta = instance._meta
return build_url(f"/admin/{meta.app_label}/{meta.model_name}/{instance.pk}/change/")
def _slack_repo_research_dto(
team_id: int, state: dict, repo_research_runs_by_id: dict, *, build_task_view_url
) -> contracts.SlackThreadContextRepoResearchDTO | None:
from posthog.storage import object_storage # noqa: PLC0415
research_task_id = state.get("repo_research_task_id")
research_run_id = state.get("repo_research_run_id")
if not research_task_id or not research_run_id:
return None
research_run = repo_research_runs_by_id.get(research_run_id)
sandbox_url = None
log_url = None
run_status = None
if research_run is not None:
sandbox_url = (research_run.state if isinstance(research_run.state, dict) else {}).get("sandbox_url")
run_status = research_run.status
try:
log_url = object_storage.get_presigned_url(research_run.log_url, expiration=3600)
except Exception:
logger.exception("slack_thread_context_research_log_presign_failed", extra={"run_id": research_run_id})
log_url = None
# Prefer the run's actual id (prefixed dispatches persist it); fall back to derived when the row is gone.
workflow_id = (
research_run.workflow_id
if research_run is not None
else TaskRun.get_workflow_id(research_task_id, research_run_id)
)
return contracts.SlackThreadContextRepoResearchDTO(
task_id=research_task_id,
run_id=research_run_id,
status=run_status,
task_processing_workflow_id=workflow_id,
task_processing_workflow_url=_temporal_workflow_url(workflow_id),
sandbox_url=sandbox_url,
task_view_url=build_task_view_url(
f"/project/{team_id}/tasks/{research_task_id}?runId={research_run_id}&ph_debug=true"
),
log_url=log_url,
)
def resolve_slack_thread_context(
team_id: int, user_id: int | None, *, channel: str, thread_ts: str, url: str, build_url
) -> contracts.SlackThreadContextResult:
"""Resolve a parsed Slack permalink to its task, runs, and Temporal workflow handles.
Caller passes the already-parsed ``(channel, thread_ts)`` and a ``build_url`` callable
(``request.build_absolute_uri``) so the facade stays request-agnostic. The mapping is filtered
through the backing task's visibility after the caller enforces the internal-debug gate.
"""
from posthog.storage import object_storage # noqa: PLC0415
from products.slack_app.backend.models import ( # noqa: PLC0415 — cross-product import kept off the api import path
SlackThreadTaskMapping,
)
mapping = (
SlackThreadTaskMapping.objects.select_related("task", "task__created_by")
.filter(channel=channel, thread_ts=thread_ts, team_id=team_id, task__deleted=False)
.filter(task_run_visibility_q(user_id))
.first()
)
if mapping is None:
# No run may exist because the message is still stuck (or was deduped) in the
# per-conversation queue workflow, so derive its handle anyway. Only possible
# when the team maps to a single Slack workspace — with several, the guess
# could point at another workspace's workflow.
workspace_ids = list({row.integration_id for row in IntegrationManager.slack.oauth.list(team_id)})
workspace_id = workspace_ids[0] if len(workspace_ids) == 1 else None
queue_workflow_id = _slack_queue_workflow_id(workspace_id, channel, thread_ts)
return contracts.SlackThreadContextResult(
outcome="no_mapping",
no_mapping_thread=contracts.SlackThreadContextThreadDTO(
url=url,
channel=channel,
thread_ts=thread_ts,
slack_workspace_id=workspace_id,
mentioning_slack_user_id=None,
queue_workflow_id=queue_workflow_id,
queue_workflow_url=_temporal_workflow_url(queue_workflow_id),
),
)
task = mapping.task
runs = list(TaskRun.objects.filter(task=task).order_by("created_at", "id"))
repo_research_run_ids = [
rid for run in runs if (rid := (run.state if isinstance(run.state, dict) else {}).get("repo_research_run_id"))
]
repo_research_runs_by_id = (
{str(r.id): r for r in TaskRun.objects.filter(team=task.team, id__in=repo_research_run_ids)}
if repo_research_run_ids
else {}
)
task_url = build_url(f"/project/{task.team_id}/tasks/{task.id}?ph_debug=true")
run_dtos: list[contracts.SlackThreadContextRunDTO] = []
for run in runs:
state = run.state if isinstance(run.state, dict) else {}
output = run.output if isinstance(run.output, dict) else {}
task_processing_workflow_id = run.workflow_id
mention_workflow_id = state.get("slack_mention_workflow_id")
try:
presigned_log_url = object_storage.get_presigned_url(run.log_url, expiration=3600)
except Exception:
logger.exception("slack_thread_context_log_presign_failed", extra={"run_id": str(run.id)})
presigned_log_url = None
run_dtos.append(
contracts.SlackThreadContextRunDTO(
id=str(run.id),
status=run.status,
created_at=run.created_at,
completed_at=run.completed_at,
sandbox_url=state.get("sandbox_url"),
pr_url=output.get("pr_url"),
error_message=run.error_message,
task_processing_workflow_id=task_processing_workflow_id,
task_processing_workflow_url=_temporal_workflow_url(task_processing_workflow_id),
mention_workflow_id=mention_workflow_id,
mention_workflow_url=_temporal_workflow_url(mention_workflow_id),
task_view_url=build_url(f"/project/{task.team_id}/tasks/{task.id}?runId={run.id}&ph_debug=true"),
log_url=presigned_log_url,
repo_research=_slack_repo_research_dto(
task.team_id, state, repo_research_runs_by_id, build_task_view_url=build_url
),
admin_url=_admin_change_url(run, build_url=build_url),
)
)
queue_workflow_id = _slack_queue_workflow_id(mapping.slack_workspace_id, channel, thread_ts)
context = contracts.SlackThreadContextDTO(
thread=contracts.SlackThreadContextThreadDTO(
url=url,
channel=channel,
thread_ts=thread_ts,
slack_workspace_id=mapping.slack_workspace_id,
mentioning_slack_user_id=mapping.mentioning_slack_user_id,
queue_workflow_id=queue_workflow_id,
queue_workflow_url=_temporal_workflow_url(queue_workflow_id),
mapping_admin_url=_admin_change_url(mapping, build_url=build_url),
),
task=contracts.SlackThreadContextTaskDTO(
id=str(task.id),
team_id=task.team_id,
title=task.title,
repository=task.repository,
origin_product=task.origin_product,
created_at=task.created_at,
url=task_url,
admin_url=_admin_change_url(task, build_url=build_url),
),
runs=run_dtos,
)
return contracts.SlackThreadContextResult(outcome="ok", context=context)
# --- Id-based bridges to the sandbox/agent-command surface ---
# These take a run id (not an ORM TaskRun) so callers never hold a tasks model. The heavy
# service modules are imported lazily to keep them off this module's import path.
def create_sandbox_connection_token(run_id: str | UUID, user_id: int, distinct_id: str) -> str:
"""Mint a short-lived connection token for talking to a run's live sandbox."""
from products.tasks.backend.logic.services.connection_token import ( # noqa: PLC0415 — keep sandbox deps off the api import path
create_sandbox_connection_token as _create,
)
run = TaskRun.objects.select_related("task").get(id=run_id)
return _create(run, user_id, distinct_id)
def send_cancel(run_id: str | UUID, *, auth_token: str | None = None):
"""Cancel the agent running in a run's live sandbox."""
from products.tasks.backend.logic.services.agent_command import ( # noqa: PLC0415 — keep sandbox deps off the api import path
send_cancel as _send_cancel,
)
run = TaskRun.objects.select_related("task").get(id=run_id)
return _send_cancel(run, auth_token=auth_token)
# --- Channels & task threads ---
_CHANNEL_NAME_SEPARATORS = re.compile(r"[^a-z0-9]+")
def normalize_channel_name(name: str) -> str:
"""Slack-style channel key: lowercase letters, digits and dashes, with every run of
anything else becoming a single dash. Must stay in step with ``normalizeChannelName``
in ``channelName.ts``, or a name is stored in a shape the field cannot produce.
Returns "" for a name with nothing usable in it, which callers reject.
"""
return _CHANNEL_NAME_SEPARATORS.sub("-", name.strip().lower()).strip("-")[:128].strip("-")
PERSONAL_SPACE_NAMES = frozenset({Channel.PERSONAL_CHANNEL_NAME, Channel.PERSONAL_CHANNEL_LABEL})
RESERVED_CHANNEL_NAMES = PERSONAL_SPACE_NAMES | {Channel.GENERAL_CHANNEL_NAME}
def is_personal_space_name(name: str) -> bool:
"""Reads as somebody's private space. Surfaces holding a bare name decide the lock and
the label from it, so a shared space under one of these presents itself as private."""
return normalize_channel_name(name) in PERSONAL_SPACE_NAMES
def is_reserved_channel_name(name: str) -> bool:
"""Reads as one of the system spaces. Renaming a space to the general name would also
make it permanently unrenameable, since the guards fall back to the name."""
return normalize_channel_name(name) in RESERVED_CHANNEL_NAMES
def _set_channel_star(channel_id: UUID, team_id: int, user_id: int, *, starred: bool) -> None:
if starred:
ChannelStar.objects.get_or_create(channel_id=channel_id, user_id=user_id, defaults={"team_id": team_id})
else:
ChannelStar.objects.filter(channel_id=channel_id, user_id=user_id).delete()
def _is_channel_starred(channel_id: UUID, user_id: int) -> bool:
return ChannelStar.objects.filter(channel_id=channel_id, user_id=user_id).exists()
def _channel_to_dto(channel: Channel, *, starred: bool = False) -> contracts.ChannelDTO:
return contracts.ChannelDTO(
id=channel.id,
name=channel.name,
channel_type=channel.channel_type,
system_role=channel.system_role,
github_integration=channel.github_integration_id,
repositories=channel.repositories,
auto_archive_after_days=channel.auto_archive_after_days,
created_at=channel.created_at,
created_by=_user_basic_info(channel.created_by if channel.created_by_id else None),
starred=starred,
)
def _team_channels(team_id: int) -> QuerySet[Channel]:
# for_team rather than a bare team_id filter so these reads also resolve outside request
# scope (Temporal activities), where the fail-closed manager raises on an unscoped read.
return Channel.objects.for_team(team_id)
def _ensure_system_channel(
team_id: int,
user_id: int | None,
*,
role: str,
owner_lookup: dict[str, Any],
legacy_lookup: dict[str, Any],
create_defaults: dict[str, Any],
) -> tuple[Channel, bool]:
"""``legacy_lookup`` must be covered by a unique constraint; that is what makes the
IntegrityError fallback safe under concurrent provisioning calls."""
created = False
channels = _team_channels(team_id).select_related("created_by")
channel = channels.filter(system_role=role, deleted=False, **owner_lookup).first()
if channel is None:
channel = channels.filter(**legacy_lookup).first()
if channel is None:
try:
channel, created = channels.get_or_create(
team_id=team_id, **legacy_lookup, defaults={**create_defaults, "system_role": role}
)
except IntegrityError:
channel, created = channels.get(team_id=team_id, **legacy_lookup), False
if created and channel.channel_type == Channel.ChannelType.PUBLIC:
_emit_channel_created(channel, user_id)
if channel.system_role != role:
channel.system_role = role
channel.save(update_fields=["system_role"])
return channel, created
PERSONAL_LEGACY_SHAPE: dict[str, Any] = {"channel_type": Channel.ChannelType.PERSONAL}
GENERAL_LEGACY_SHAPE: dict[str, Any] = {
"channel_type": Channel.ChannelType.PUBLIC,
"name": Channel.GENERAL_CHANNEL_NAME,
}
def _ensure_personal_channel(team_id: int, user_id: int) -> tuple[Channel, bool]:
return _ensure_system_channel(
team_id,
user_id,
role=Channel.SystemRole.PERSONAL,
owner_lookup={"created_by_id": user_id},
legacy_lookup={"created_by_id": user_id, **PERSONAL_LEGACY_SHAPE, "deleted": False},
create_defaults={"name": Channel.PERSONAL_CHANNEL_NAME},
)
def ensure_personal_channel_id(team_id: int, user_id: int) -> UUID:
"""Get-or-create the user's personal "#me" channel and return its id.
For callers outside a request (Temporal activities) that need somewhere to file a task.
"""
return _ensure_personal_channel(team_id, user_id)[0].id
def _ensure_general_channel(team_id: int, user_id: int | None) -> tuple[Channel, bool]:
return _ensure_system_channel(
team_id,
user_id,
role=Channel.SystemRole.GENERAL,
owner_lookup={},
legacy_lookup={**GENERAL_LEGACY_SHAPE, "deleted": False},
create_defaults={"created_by_id": user_id},
)
def _matches_legacy_shape(channel: Channel, legacy: dict[str, Any]) -> bool:
return all(getattr(channel, key) == value for key, value in legacy.items())
def general_channel_q(prefix: str = "") -> Q:
if prefix == "channel":
return Q(channel__system_role=Channel.SystemRole.GENERAL) | Q(
channel__system_role__isnull=True,
channel__channel_type=Channel.ChannelType.PUBLIC,
channel__name=Channel.GENERAL_CHANNEL_NAME,
)
if prefix:
raise ValueError(f"Unsupported channel relation: {prefix}")
return Q(system_role=Channel.SystemRole.GENERAL) | Q(
system_role__isnull=True,
channel_type=Channel.ChannelType.PUBLIC,
name=Channel.GENERAL_CHANNEL_NAME,
)
def personal_channel_q(prefix: str = "") -> Q:
if prefix == "channel":
return Q(channel__system_role=Channel.SystemRole.PERSONAL) | Q(
channel__system_role__isnull=True,
channel__channel_type=Channel.ChannelType.PERSONAL,
)
if prefix:
raise ValueError(f"Unsupported channel relation: {prefix}")
return Q(system_role=Channel.SystemRole.PERSONAL) | Q(
system_role__isnull=True,
channel_type=Channel.ChannelType.PERSONAL,
)
def find_general_channel_id(team_id: int) -> UUID | None:
"""The team's general space, or ``None`` when nobody has provisioned one. Read-only, so
a product filing work into that space can gate on its existence instead of bringing the
team's default spaces into being as a side effect."""
channel = (
_team_channels(team_id)
.filter(general_channel_q(), deleted=False)
# A stamped row wins over an unstamped one, in the vanishingly rare case a team has both.
.order_by(F("system_role").asc(nulls_last=True))
.first()
)
return channel.id if channel is not None else None
def _is_general_channel(channel: Channel) -> bool:
"""Must match ``isGeneralChannel`` in ``channelName.ts``: a row with no role but the
general name is still the team's general space."""
if channel.system_role is not None:
return channel.system_role == Channel.SystemRole.GENERAL
return _matches_legacy_shape(channel, GENERAL_LEGACY_SHAPE)
def provision_default_channels(team_id: int, user_id: int) -> contracts.ProvisionedChannelsDTO:
"""The created flags let a client distinguish "this call provisioned the space"
(first user in the team) from inheriting one that already existed."""
_, personal_created = _ensure_personal_channel(team_id, user_id)
_, general_created = _ensure_general_channel(team_id, user_id)
return contracts.ProvisionedChannelsDTO(
channels=list_channels(team_id, user_id),
personal_created=personal_created,
general_created=general_created,
)
def list_channels(team_id: int, user_id: int | None) -> list[contracts.ChannelDTO]:
channels = list(
_team_channels(team_id)
.select_related("created_by")
.filter(Channel.visible_to_q(user_id))
.order_by("name", "id")
)
starred_ids: set = (
set(ChannelStar.objects.filter(team_id=team_id, user_id=user_id).values_list("channel_id", flat=True))
if user_id is not None
else set()
)
return [_channel_to_dto(channel, starred=channel.id in starred_ids) for channel in channels]
def list_channel_contributors(team_id: int, user_id: int | None) -> list[contracts.ChannelContributorsDTO]:
"""The people who own a task or a canvas in each channel the requester can see.
Archived tasks count, because their owners still worked in the channel. Deleted tasks
and canvases do not. A channel with no owner has no entry."""
channel_ids = list(_team_channels(team_id).filter(Channel.visible_to_q(user_id)).values_list("id", flat=True))
if not channel_ids:
return []
task_rows = (
Task.objects.filter(
task_visibility_q(user_id, team_id),
team_id=team_id,
channel_id__in=channel_ids,
deleted=False,
internal=False,
created_by_id__isnull=False,
)
.values("channel_id", "created_by_id")
.annotate(last_active=Max(Coalesce("last_activity_at", "created_at")))
)
from products.canvas.backend.facade import (
access as canvas_access, # noqa: PLC0415 — keeps canvas off django.setup()
)
owner_rows = [(row["channel_id"], row["created_by_id"], row["last_active"]) for row in task_rows]
owner_rows.extend(
(row.channel_id, row.created_by_id, row.last_active)
for row in canvas_access.canvas_owner_activity(team_id=team_id, channel_ids=channel_ids)
)
last_active: dict[UUID, dict[int, datetime]] = {}
for channel_id, created_by_id, active_at in owner_rows:
per_channel = last_active.setdefault(channel_id, {})
previous = per_channel.get(created_by_id)
if previous is None or active_at > previous:
per_channel[created_by_id] = active_at
user_ids = {owner_id for owners in last_active.values() for owner_id in owners}
users = {user.id: user for user in User.objects.filter(id__in=user_ids)}
contributors: list[contracts.ChannelContributorsDTO] = []
for channel_id, owners in last_active.items():
ranked = sorted(owners.items(), key=lambda owner: (-owner[1].timestamp(), owner[0]))
people = [info for owner_id, _ in ranked if (info := _user_basic_info(users.get(owner_id))) is not None]
if people:
contributors.append(contracts.ChannelContributorsDTO(channel=channel_id, people=people))
return contributors
def _emit_channel_created(channel: Channel, user_id: int | None) -> None:
"""Announce a newly-created public channel in its own feed as a system row
("Ann created this context"). Server-emitted so the announcement appears no
matter which client (or integration) created the channel. Best-effort — a
feed-write failure must never break channel creation. The fail-closed
``TeamScopedManager`` raises without team context, so callers outside a
request (temporal, MCP) must wrap in ``team_scope()`` or the announcement
is swallowed here and only logged."""
try:
ChannelFeedMessage.objects.create(
team_id=channel.team_id,
channel_id=channel.id,
author_id=user_id,
author_kind=ChannelFeedMessage.AuthorKind.SYSTEM,
event="channel_created",
payload={"channel_name": channel.name},
)
except Exception:
logger.exception("Failed to emit channel_created feed message", extra={"channel_id": str(channel.id)})
def resolve_channel(team_id: int, user_id: int | None, *, name: str, star: bool) -> contracts.ChannelDTO | None:
"""Resolve-or-create a public channel by (normalized) name. ``None`` for empty names.
The general name resolves the team's general space, which cannot then be renamed away.
Emits a ``channel_created`` feed message the first time a channel is created, and (unless
``star`` is false) stars the channel for whoever created it. Resolving a channel that
already exists leaves the requester's star alone — only creation stars."""
normalized = normalize_channel_name(name)
if not normalized:
return None
if normalized == Channel.GENERAL_CHANNEL_NAME:
# Resolving by name here would produce a second, unstamped general space, so
# every path that can create one goes through the role-aware helper.
channel, created = _ensure_general_channel(team_id, user_id)
else:
created = False
try:
channel, created = Channel.objects.select_related("created_by").get_or_create(
team_id=team_id,
name=normalized,
channel_type=Channel.ChannelType.PUBLIC,
deleted=False,
defaults={"created_by_id": user_id},
)
except IntegrityError:
channel = Channel.objects.select_related("created_by").get(
team_id=team_id, name=normalized, channel_type=Channel.ChannelType.PUBLIC, deleted=False
)
if created:
_emit_channel_created(channel, user_id)
if user_id is None:
starred = False
elif not created:
starred = _is_channel_starred(channel.id, user_id)
else:
starred = star
if star:
_set_channel_star(channel.id, team_id, user_id, starred=True)
return _channel_to_dto(channel, starred=starred)
def _channel_member_infos(channel: Channel, team_id: int) -> list[contracts.TaskUserBasicInfo]:
members = (
ChannelMembership.objects.for_team(team_id)
.filter(channel_id=channel.id)
.select_related("user")
.order_by("created_at")
)
return [info for member in members if (info := _user_basic_info(member.user)) is not None]
def create_private_channel(
team_id: int, user_id: int, *, name: str, member_ids: list[int], star: bool
) -> contracts.ChannelDTO | None:
normalized = normalize_channel_name(name)
if not normalized or is_reserved_channel_name(normalized):
return None
team = Team.objects.get(id=team_id)
accessible = set(team.all_users_with_access().filter(id__in=member_ids).values_list("id", flat=True))
target_ids = {user_id, *accessible}
with transaction.atomic():
channel = Channel.objects.for_team(team_id).create(
team_id=team_id,
name=normalized,
channel_type=Channel.ChannelType.PRIVATE,
created_by_id=user_id,
)
for member_id in target_ids:
ChannelMembership.objects.for_team(team_id).create(
team_id=team_id, channel_id=channel.id, user_id=member_id
)
_emit_channel_created(channel, user_id)
starred = False
if star:
_set_channel_star(channel.id, team_id, user_id, starred=True)
starred = True
return _channel_to_dto(channel, starred=starred)
def list_channel_members(
channel_id: str | UUID, team_id: int, user_id: int | None
) -> list[contracts.TaskUserBasicInfo] | None:
channel = _visible_channel(channel_id, team_id, user_id)
if channel is None:
return None
return _channel_member_infos(channel, team_id)
def _reset_channel_memberships(channel: Channel, team_id: int, user_id: int | None) -> None:
memberships = ChannelMembership.objects.for_team(team_id).filter(channel_id=channel.id)
memberships.delete()
if channel.channel_type != Channel.ChannelType.PRIVATE:
return
seed_ids = {member_id for member_id in (channel.created_by_id, user_id) if member_id is not None}
for member_id in seed_ids:
ChannelMembership.objects.for_team(team_id).create(team_id=team_id, channel_id=channel.id, user_id=member_id)
def set_channel_members(
channel_id: str | UUID, team_id: int, user_id: int | None, *, member_ids: list[int]
) -> list[contracts.TaskUserBasicInfo] | str:
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return "not_found"
if channel.channel_type != Channel.ChannelType.PRIVATE:
return "not_private"
submitted = {*member_ids}
accessible = set(channel.team.all_users_with_access().filter(id__in=submitted).values_list("id", flat=True))
if accessible != submitted:
return "invalid_member"
target_ids = set(submitted)
if channel.created_by_id is not None:
target_ids.add(channel.created_by_id)
memberships = ChannelMembership.objects.for_team(team_id).filter(channel_id=channel.id)
existing = set(memberships.values_list("user_id", flat=True))
for member_id in target_ids - existing:
ChannelMembership.objects.for_team(team_id).create(
team_id=team_id, channel_id=channel.id, user_id=member_id
)
to_remove = existing - target_ids
if to_remove:
memberships.filter(user_id__in=to_remove).delete()
return _channel_member_infos(channel, team_id)
def update_channel(
channel_id: str | UUID,
team_id: int,
user_id: int | None,
*,
can_manage_shared_auto_archive: bool,
name: str | None = None,
github_integration: IntegrationRecord | None = None,
repositories: list[str] | None = None,
auto_archive_after_days: int | None | _AutoArchiveUnchanged = _AUTO_ARCHIVE_UNCHANGED,
channel_type: str | None = None,
) -> contracts.ChannelDTO | str:
try:
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return "not_found"
if channel.channel_type == Channel.ChannelType.PERSONAL:
if channel.created_by_id != user_id:
return "not_found"
if name is not None or channel_type is not None:
return "personal"
elif not isinstance(auto_archive_after_days, _AutoArchiveUnchanged) and not can_manage_shared_auto_archive:
return "auto_archive_forbidden"
if (name is not None or channel_type is not None) and _is_general_channel(channel):
return "general"
update_fields: list[str] = []
previous_repositories = list(channel.repositories or [])
previous_integration_id = channel.github_integration_id
if channel_type is not None and channel_type != channel.channel_type:
channel.channel_type = channel_type
update_fields.append("channel_type")
_reset_channel_memberships(channel, team_id, user_id)
if name is not None:
normalized = normalize_channel_name(name)
if not normalized:
return "invalid_name"
channel.name = normalized
update_fields.append("name")
if repositories is not None:
channel.repositories = repositories
channel.github_integration_id = (
github_integration.id if repositories and github_integration is not None else None
)
update_fields.extend(["repositories", "github_integration"])
if not isinstance(auto_archive_after_days, _AutoArchiveUnchanged):
channel.auto_archive_after_days = auto_archive_after_days
update_fields.append("auto_archive_after_days")
if not update_fields:
return _channel_to_dto(channel)
channel.save(update_fields=[*update_fields, "updated_at"])
except IntegrityError:
return "name_taken"
if repositories is not None:
capture_repository_config_changed(
team=channel.team,
user_id=user_id,
subject="space",
trigger="space_settings_edit",
previous_repositories=previous_repositories,
repositories=channel.repositories,
previous_integration_id=previous_integration_id,
integration_id=channel.github_integration_id,
channel_id=str(channel.id),
)
return _channel_to_dto(channel)
def delete_channel(channel_id: str | UUID, team_id: int, user_id: int | None) -> str:
from products.canvas.backend.facade import (
access as canvas_facade, # noqa: PLC0415 — keeps canvas off django.setup()
)
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return "not_found"
if channel.channel_type == Channel.ChannelType.PERSONAL:
return "personal" if channel.created_by_id == user_id else "not_found"
if _is_general_channel(channel):
return "general"
if channel.tasks.filter(deleted=False, archived=False).exists() or canvas_facade.channel_has_canvases(
team_id=team_id, channel_id=channel.id
):
return "not_empty"
channel.tasks.filter(deleted=False).update(channel=None)
channel.deleted = True
channel.save(update_fields=["deleted", "updated_at"])
return "ok"
# Per-channel ceiling on feed rows — the feed holds rare lifecycle announcements, so the
# cap exists to stop one member making the feed unboundedly expensive to store and read.
CHANNEL_FEED_MAX_MESSAGES = 500
def _channel_feed_message_to_dto(message: ChannelFeedMessage) -> contracts.ChannelFeedMessageDTO:
return contracts.ChannelFeedMessageDTO(
id=message.id,
channel=message.channel_id,
author_kind=message.author_kind,
event=message.event,
payload=message.payload or {},
content=message.content,
created_at=message.created_at,
author=_user_basic_info(message.author if message.author_id else None),
)
def visible_channels_q(user_id: int | None, *, relation: Literal["", "channel"] = "") -> Q:
"""The channel-visibility rule as a queryset filter; see ``Channel.visible_to_q``
for the semantics. Exported for cross-product callers filtering channel-joined
querysets. Single-object callers use ``get_channel``."""
return Channel.visible_to_q(user_id, relation=relation)
def visible_tasks_q(user_id: int | None, *, relation: Literal["", "task"] = "") -> Q:
return task_run_visibility_q(user_id) if relation == "task" else task_visibility_q(user_id)
def channel_exists(team_id: int, channel_id: str | UUID, user_id: int | None) -> bool:
"""Whether ``channel_id`` is a live channel in this team that the user may see."""
return (
Channel.objects.for_team(team_id).filter(Channel.visible_to_q(user_id), id=channel_id, deleted=False).exists()
)
def _visible_channel(channel_id: str | UUID, team_id: int, user_id: int | None) -> Channel | None:
return (
_team_channels(team_id)
.select_related("created_by")
.filter(visible_channels_q(user_id), id=channel_id, deleted=False)
.first()
)
def _locked_visible_channel(
channel_id: str | UUID, team_id: int, user_id: int | None, *, no_key: bool = False
) -> Channel | None:
channel = (
Channel.objects.for_team(team_id).select_for_update(no_key=no_key).filter(id=channel_id, deleted=False).first()
)
if channel is None:
return None
return _visible_channel(channel_id, team_id, user_id)
def list_channel_feed_messages(
channel_id: str | UUID, team_id: int, user_id: int | None
) -> list[contracts.ChannelFeedMessageDTO] | None:
"""A channel's system-announcement feed, ascending. ``None`` when the channel isn't visible.
Bounded to the newest ``CHANNEL_FEED_MAX_MESSAGES``: the feed holds rare lifecycle
events, and the write path caps a channel at the same count. Add real pagination
before any per-task or per-thread event lands here."""
if _visible_channel(channel_id, team_id, user_id) is None:
return None
messages = (
ChannelFeedMessage.objects.filter(channel_id=channel_id, team_id=team_id, deleted=False)
.select_related("author")
.order_by("-created_at", "-id")[:CHANNEL_FEED_MAX_MESSAGES]
)
return [_channel_feed_message_to_dto(message) for message in reversed(messages)]
def create_channel_feed_message(
channel_id: str | UUID,
team_id: int,
user_id: int | None,
*,
event: str,
payload: dict,
created_at: datetime | None = None,
) -> contracts.ChannelFeedMessageDTO | None | str:
with transaction.atomic():
if _locked_visible_channel(channel_id, team_id, user_id) is None:
return None
if (
ChannelFeedMessage.objects.filter(channel_id=channel_id, team_id=team_id, deleted=False).count()
>= CHANNEL_FEED_MAX_MESSAGES
):
return "full"
fields: dict = {
"team_id": team_id,
"channel_id": channel_id,
"author_id": user_id,
"author_kind": ChannelFeedMessage.AuthorKind.HUMAN,
"event": event,
"payload": payload or {},
}
if created_at is not None:
fields["created_at"] = created_at
message = ChannelFeedMessage.objects.create(**fields)
return _channel_feed_message_to_dto(message)
def get_channel(channel_id: str | UUID, team_id: int, user_id: int | None) -> contracts.ChannelDTO | None:
"""One channel the requester may read, or ``None``."""
channel = _visible_channel(channel_id, team_id, user_id)
if channel is None:
return None
starred = user_id is not None and _is_channel_starred(channel.id, user_id)
return _channel_to_dto(channel, starred=starred)
# --- Channel instructions (CONTEXT.md) ---
# Generous cap on the markdown blob; channel instructions are descriptions, not documents.
CHANNEL_INSTRUCTIONS_MAX_BYTES = 100_000
MAX_CHANNEL_INSTRUCTIONS_VERSION = 2000
@dataclass
class ChannelInstructionsTooLargeError(Exception):
max_bytes: int
@dataclass
class ChannelInstructionsVersionConflictError(Exception):
current_version: int
@dataclass
class ChannelInstructionsVersionLimitError(Exception):
max_version: int
def _instructions_to_dto(row: ChannelInstructions) -> contracts.ChannelInstructionsDTO:
return contracts.ChannelInstructionsDTO(
channel=row.channel_id,
content=row.content,
version=row.version,
created_at=row.created_at,
created_by=_user_basic_info(row.created_by if row.created_by_id else None),
)
def _blank_instructions_dto(channel: Channel) -> contracts.ChannelInstructionsDTO:
"""A channel with no published instructions reads as blank version 0, so
readers never 404 and a first publish guards on ``base_version: 0``."""
return contracts.ChannelInstructionsDTO(channel=channel.id, content="", version=0)
def get_channel_instructions(
channel_id: str | UUID, team_id: int, user_id: int | None
) -> contracts.ChannelInstructionsDTO | None:
"""The channel's latest instructions (blank version 0 when none exist).
``None`` when the channel isn't visible."""
channel = _visible_channel(channel_id, team_id, user_id)
if channel is None:
return None
latest = (
ChannelInstructions.objects.filter(channel_id=channel.id, deleted=False, is_latest=True)
.select_related("created_by")
.first()
)
return _instructions_to_dto(latest) if latest is not None else _blank_instructions_dto(channel)
def desktop_users_in_team(team: Team, exclude_user_id: int) -> list[str]:
channels = (
Channel.objects.for_team(team.id)
.filter(
personal_channel_q(),
deleted=False,
created_by__in=team.all_users_with_access(),
)
.exclude(created_by_id=exclude_user_id)
.select_related("created_by")
.order_by("created_at")[:4]
)
return [
channel.created_by.first_name or channel.created_by.email.split("@")[0]
for channel in channels
if channel.created_by
]
def organization_has_context(organization_id: UUID | str) -> bool:
contents = (
ChannelInstructions.objects.unscoped()
.filter(
general_channel_q("channel"),
team__organization_id=organization_id,
channel__deleted=False,
deleted=False,
is_latest=True,
version__gt=0,
)
.exclude(content="")
.values_list("content", flat=True)[:20]
)
return any(content.strip() for content in contents)
def list_channel_instruction_versions(
channel_id: str | UUID, team_id: int, user_id: int | None
) -> list[contracts.ChannelInstructionsDTO] | None:
"""The channel's instruction history, newest first. ``None`` when the channel isn't visible."""
if _visible_channel(channel_id, team_id, user_id) is None:
return None
versions = (
ChannelInstructions.objects.filter(channel_id=channel_id, team_id=team_id, deleted=False)
.select_related("created_by")
.order_by("-version", "-created_at", "-id")[:200]
)
return [_instructions_to_dto(row) for row in versions]
def task_can_publish_channel_instructions(task_id: str | UUID, team_id: int) -> bool:
# Legacy loop runs could only publish to the channel their loop targeted, and that config is gone.
return Task.objects.filter(id=task_id, team_id=team_id).exclude(origin_product=Task.OriginProduct.LOOP).exists()
def mcp_tool_allowlist_for_task(task_id: str | UUID) -> list[str] | None:
"""The PostHog MCP tools a run picked at dispatch, or None when the run is not narrowed.
Scoped by task rather than by team, because the caller's authority here is a run token
minted for exactly this task. A malformed snapshot reads as an empty list, so callers fail
closed.
"""
task = Task.objects.filter(id=task_id).only("id", "origin_product", "state").first()
return task.mcp_tool_allowlist if task is not None else None
def capture_context_wiki_changed(
organization_id: str | UUID,
team_id: int,
channel_id: str | UUID,
user_id: int | None,
*,
actor_type: Literal["user_or_api", "task_agent"],
is_first_version: bool,
content_bytes: int,
base_version_provided: bool,
) -> bool:
channel = (
Channel.objects.unscoped()
.select_related("team")
.filter(id=channel_id, team_id=team_id, team__organization_id=organization_id)
.first()
)
if channel is None:
return False
capture_space_context_changed(
team=channel.team,
user_id=user_id,
channel_id=str(channel.id),
action="published",
source="user" if actor_type == "user_or_api" else "agent",
previous_version=None,
content_bytes=content_bytes,
base_version_provided=base_version_provided,
storage="context_wiki",
actor_type=actor_type,
is_first_version=is_first_version,
)
return True
def publish_channel_instructions(
channel_id: str | UUID,
team_id: int,
user_id: int | None,
*,
content: str,
base_version: int | None = None,
source: Literal["user", "agent"] = "user",
) -> contracts.ChannelInstructionsDTO | None:
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return None
if len(content.encode("utf-8")) > CHANNEL_INSTRUCTIONS_MAX_BYTES:
raise ChannelInstructionsTooLargeError(max_bytes=CHANNEL_INSTRUCTIONS_MAX_BYTES)
current_latest = (
ChannelInstructions.objects.select_for_update()
.filter(channel_id=channel.id, deleted=False, is_latest=True)
.order_by("-version", "-created_at", "-id")
.first()
)
current_version = current_latest.version if current_latest is not None else 0
previous_content_bytes = len(current_latest.content.encode("utf-8")) if current_latest is not None else None
if base_version is not None and base_version != current_version:
raise ChannelInstructionsVersionConflictError(current_version=current_version)
if current_version >= MAX_CHANNEL_INSTRUCTIONS_VERSION:
raise ChannelInstructionsVersionLimitError(max_version=MAX_CHANNEL_INSTRUCTIONS_VERSION)
if current_latest is not None:
ChannelInstructions.objects.filter(pk=current_latest.pk).update(is_latest=False)
try:
with transaction.atomic():
published = ChannelInstructions.objects.create(
team_id=team_id,
channel_id=channel.id,
content=content,
version=current_version + 1,
is_latest=True,
created_by_id=user_id,
)
except IntegrityError:
latest = (
ChannelInstructions.objects.filter(channel_id=channel.id, deleted=False)
.order_by("-version", "-created_at", "-id")
.first()
)
raise ChannelInstructionsVersionConflictError(current_version=latest.version if latest is not None else 0)
ChannelContextGeneration.objects.filter(channel_id=channel.id).update(task_id=None)
capture_space_context_changed(
team=channel.team,
user_id=user_id,
channel_id=str(channel.id),
action="published",
source=source,
previous_version=current_version,
new_version=published.version,
content_bytes=len(content.encode("utf-8")),
previous_content_bytes=previous_content_bytes,
base_version_provided=base_version is not None,
)
return _instructions_to_dto(published)
def delete_channel_instructions(
channel_id: str | UUID, team_id: int, user_id: int | None, *, source: Literal["user", "agent"] = "user"
) -> int | None:
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return None
previous_version = (
ChannelInstructions.objects.filter(channel_id=channel.id, deleted=False)
.order_by("-version")
.values_list("version", flat=True)
.first()
or 0
)
count = (
ChannelInstructions.objects.select_for_update()
.filter(channel_id=channel.id, deleted=False)
.update(deleted=True, is_latest=False)
)
ChannelContextGeneration.objects.filter(channel_id=channel.id).update(task_id=None)
if count:
capture_space_context_changed(
team=channel.team,
user_id=user_id,
channel_id=str(channel.id),
action="cleared",
source=source,
previous_version=previous_version,
versions_deleted=count,
)
return count
def get_channel_context_generation(
channel_id: str | UUID, team_id: int, user_id: int | None
) -> str | None | Literal["not_found"]:
"""The id of the task currently generating the channel's CONTEXT.md, or ``None``."""
channel = _visible_channel(channel_id, team_id, user_id)
if channel is None:
return "not_found"
marker = ChannelContextGeneration.objects.filter(channel_id=channel.id).first()
return str(marker.task_id) if marker is not None and marker.task_id else None
def set_channel_context_generation(
channel_id: str | UUID, team_id: int, user_id: int | None, *, task_id: str | UUID | None
) -> str | None | Literal["not_found", "invalid_task"]:
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return "not_found"
if task_id is not None and not task_exists(task_id, team_id):
return "invalid_task"
ChannelContextGeneration.objects.update_or_create(
channel_id=channel.id, defaults={"team_id": team_id, "task_id": task_id}
)
return str(task_id) if task_id else None
def start_space_setup(
channel_id: str | UUID,
team: Team,
user_id: int,
*,
request: contracts.SpaceSetupRequest,
client_provenance: TaskClientProvenance | None = None,
) -> contracts.SpaceSetupStartedDTO | None:
"""Start the one task that sets a space up for a goal or a feature.
The task runs unattended in the channel and publishes the context page itself, so it
takes over the channel's context generation marker the same way a CONTEXT.md
generation task does. ``None`` when the channel is not visible to the user.
"""
if _visible_channel(channel_id, team.id, user_id) is None:
return None
if request.kind == "goal" and not cdp_facade.is_hog_function_template_available(
"template-posthog-create-task", team
):
raise SpaceSetupUnavailableError(
"Goal setup is not available because the Create AI task workflow action is unavailable. "
"Ask an administrator to sync workflow templates, then retry setup."
)
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team.id, user_id)
if channel is None:
return None
active_setup = (
Task.objects.filter(team_id=team.id, channel_id=channel.id, origin_product=Task.OriginProduct.SPACE_SETUP)
.annotate(
setup_run_status=Subquery(
TaskRun.objects.filter(team_id=team.id, task_id=OuterRef("pk"))
.order_by("-created_at", "-id")
.values("status")[:1]
)
)
.filter(
setup_run_status__in=[TaskRun.Status.NOT_STARTED, TaskRun.Status.QUEUED, TaskRun.Status.IN_PROGRESS]
)
.exists()
)
if active_setup:
raise contracts.SpaceSetupInProgressError("Space setup is already running. Open its task to see progress.")
repository = request.repository or (channel.repositories[0] if channel.repositories else None)
request = replace(request, repository=repository)
try:
task = Task.create_and_run(
team=team,
title=space_setup_task_title(channel.name, request),
description=build_space_setup_prompt(
team_id=team.id, channel_id=str(channel.id), channel_name=channel.name, request=request
),
profile=SPACE_SETUP,
user_id=user_id,
channel=channel,
repository=repository,
options=TaskRunOptions(
adapter=SPACE_SETUP_RUNTIME_ADAPTER,
model=SPACE_SETUP_MODEL,
reasoning_effort=SPACE_SETUP_REASONING_EFFORT,
mcp_scopes=[*contracts.SPACE_SETUP_SCOPES, CONTEXT_LAYER_INTERNAL_SCOPE],
permission_mode="auto",
),
create_pr=False,
client_provenance=client_provenance,
)
except ValueError as e:
raise SpaceSetupUnavailableError(
f"Goal setup could not start: {e}. Connect the GitHub integration that owns the repository, then retry setup."
) from e
ChannelContextGeneration.objects.update_or_create(
channel_id=channel.id, defaults={"team_id": team.id, "task_id": task.id}
)
_emit_space_setup_started(channel, user_id, request=request, task_id=task.id)
return contracts.SpaceSetupStartedDTO(task_id=task.id)
def _emit_space_setup_started(
channel: Channel, user_id: int, *, request: contracts.SpaceSetupRequest, task_id: UUID
) -> None:
subject = request.goal.statement if request.goal is not None else request.feature.name if request.feature else ""
try:
with transaction.atomic():
ChannelFeedMessage.objects.create(
team_id=channel.team_id,
channel_id=channel.id,
author_id=user_id,
author_kind=ChannelFeedMessage.AuthorKind.SYSTEM,
event=SPACE_SETUP_FEED_EVENT,
payload={"kind": request.kind, "subject": subject, "task_id": str(task_id)},
)
except Exception:
logger.exception("Failed to emit space_setup_started feed message", extra={"channel_id": str(channel.id)})
def star_channel(channel_id: str | UUID, team_id: int, user_id: int, *, starred: bool) -> bool:
with transaction.atomic():
channel = _locked_visible_channel(channel_id, team_id, user_id)
if channel is None:
return False
_set_channel_star(channel.id, team_id, user_id, starred=starred)
return True
def _thread_message_to_dto(message: TaskThreadMessage) -> contracts.TaskThreadMessageDTO:
return contracts.TaskThreadMessageDTO(
id=message.id,
task=message.task_id,
author_kind=message.author_kind,
event=message.event,
payload=message.payload or {},
content=message.content,
created_at=message.created_at,
author=_user_basic_info(message.author if message.author_id else None),
forwarded_to_agent_at=message.forwarded_to_agent_at,
forwarded_by=_user_basic_info(message.forwarded_by if message.forwarded_by_id else None),
)
def _visible_task(task_id: str | UUID, team_id: int, user_id: int | None) -> Task | None:
return _visible_task_qs(team_id, user_id).filter(id=task_id).first()
def list_thread_messages(
task_id: str | UUID, team_id: int, user_id: int | None
) -> list[contracts.TaskThreadMessageDTO] | None:
"""A task's thread, ascending. ``None`` when the task isn't visible to the user."""
if _visible_task(task_id, team_id, user_id) is None:
return None
messages = (
TaskThreadMessage.objects.filter(task_id=task_id, team_id=team_id)
# The thread is human-to-human plus artifact announcements; rows written
# back when the agent finished a turn (a since-removed behavior) stay out.
.exclude(event="turn_complete")
.select_related("author", "forwarded_by")
.order_by("created_at", "id")
)
return [_thread_message_to_dto(message) for message in messages]
def create_thread_message(
task_id: str | UUID, team_id: int, user_id: int | None, *, content: str
) -> contracts.TaskThreadMessageDTO | None:
"""Add a thread message as the requester. ``None`` when the task isn't visible."""
if _visible_task(task_id, team_id, user_id) is None:
return None
message = TaskThreadMessage.objects.create(team_id=team_id, task_id=task_id, author_id=user_id, content=content)
try:
project_thread_message_activity(message)
except Exception:
logger.exception("Failed to project thread message activity", extra={"message_id": str(message.id)})
try:
mentioned_user_ids = resolve_mentioned_user_ids(
User, message.content, team_id=message.team_id, author_id=message.author_id
)
except Exception:
mentioned_user_ids = []
logger.exception("Failed to resolve thread message mentions", extra={"message_id": str(message.id)})
try:
_index_thread_message_mentions(message, mentioned_user_ids)
except Exception:
# Mention indexing is best-effort: a failure must never fail message creation or discard resolved recipients.
logger.exception("Failed to index thread message mentions", extra={"message_id": str(message.id)})
from products.tasks.backend.push_dispatcher import notify_task_thread_message # noqa: PLC0415
notify_task_thread_message(message, mentioned_user_ids)
# Fresh message: forwarded_by is None (no query) and author lazy-loads once.
return _thread_message_to_dto(message)
def _index_thread_message_mentions(message: TaskThreadMessage, mentioned_user_ids: Collection[int]) -> None:
"""Create mention index rows for @[Name](email) tokens in the message content.
Emails resolve case-insensitively, only to members of the team's organization;
self-mentions are skipped (they are never notifications).
"""
mentions = [
TaskThreadMessageMention(
team_id=message.team_id,
message_id=message.id,
task_id=message.task_id,
mentioned_user_id=mentioned_user_id,
created_at=message.created_at,
)
for mentioned_user_id in mentioned_user_ids
]
TaskThreadMessageMention.objects.for_team(message.team_id).bulk_create(
mentions,
ignore_conflicts=True,
)
for mention in mentions:
TaskActivity.record(
team_id=message.team_id,
user_id=mention.mentioned_user_id,
task_id=message.task_id,
kind=TaskActivity.Kind.MENTION,
activity_at=message.created_at,
message_id=message.id,
)
def task_comment_target_is_accessible(
*, team_id: int, user_id: int | None, task_id: str | UUID, scope: str, item_id: str | None
) -> bool:
from products.tasks.backend.logic.services.comment_activity import target_is_accessible
return target_is_accessible(team_id=team_id, user_id=user_id, task_id=task_id, scope=scope, item_id=item_id)
def task_comment_mentions_allowed(*, team_id: int, task_id: str | UUID) -> bool:
from products.tasks.backend.logic.services.comment_activity import notifications_allowed
return notifications_allowed(team_id=team_id, task_id=task_id)
def record_comment_activity(
*,
team_id: int,
comment_id: UUID,
mentioned_user_ids: Sequence[int],
include_relationship_recipients: bool = True,
target_owner_id: int | None = None,
activity_at: datetime | None = None,
) -> None:
from products.tasks.backend.logic.services.comment_activity import project_comment_activity
project_comment_activity(
team_id=team_id,
comment_id=comment_id,
mentioned_user_ids=mentioned_user_ids,
include_relationship_recipients=include_relationship_recipients,
target_owner_id=target_owner_id,
activity_at=activity_at,
)
post_comment_thread_update(team_id=team_id, comment_id=comment_id)
def enqueue_comment_activity_retry(
*,
team_id: int,
comment_id: str,
mentioned_user_ids: list[int],
include_relationship_recipients: bool,
target_owner_id: int | None,
activity_at: str | None,
) -> None:
from products.tasks.backend.tasks.tasks import ( # noqa: PLC0415 — avoids the facade/task circular import
project_task_comment_activity,
)
project_task_comment_activity.delay(
team_id=team_id,
comment_id=comment_id,
mentioned_user_ids=mentioned_user_ids,
include_relationship_recipients=include_relationship_recipients,
target_owner_id=target_owner_id,
activity_at=activity_at,
)
def list_task_artifacts(*, team_id: int, task_id: UUID) -> list[contracts.TaskArtifactDTO]:
from products.tasks.backend.logic.services.task_comments import list_artifacts
return list_artifacts(team_id=team_id, task_id=task_id)
def list_task_comments(
*,
team_id: int,
task_id: UUID,
user_id: int | None,
artifact_id: str | None,
include_resolved: bool,
limit: int,
cursor: str | None,
) -> contracts.TaskCommentPageDTO:
from products.tasks.backend.logic.services.task_comments import InvalidTaskCommentCursor, list_comments
try:
return list_comments(
team_id=team_id,
task_id=task_id,
user_id=user_id,
artifact_id=artifact_id,
include_resolved=include_resolved,
limit=limit,
cursor=cursor,
)
except InvalidTaskCommentCursor:
raise ValueError("Invalid task comment cursor") from None
def list_canvas_comments(
*,
team_id: int,
canvas_id: UUID,
canvas_name: str,
include_resolved: bool,
limit: int,
cursor: str | None,
) -> contracts.TaskCommentPageDTO:
from products.tasks.backend.logic.services.task_comments import (
InvalidTaskCommentCursor,
list_canvas_comments as list_comments_for_canvas,
)
try:
return list_comments_for_canvas(
team_id=team_id,
canvas_id=canvas_id,
canvas_name=canvas_name,
include_resolved=include_resolved,
limit=limit,
cursor=cursor,
)
except InvalidTaskCommentCursor:
raise ValueError("Invalid canvas comment cursor") from None
def retrieve_canvas_comment(
*,
team_id: int,
canvas_id: UUID,
canvas_name: str,
comment_id: UUID,
limit: int,
cursor: str | None,
content_comment_id: UUID | None,
content_offset: int,
) -> contracts.TaskCommentDetailDTO | None:
from products.tasks.backend.logic.services.task_comments import (
InvalidTaskCommentCursor,
retrieve_canvas_comment as retrieve_comment_for_canvas,
)
try:
return retrieve_comment_for_canvas(
team_id=team_id,
canvas_id=canvas_id,
canvas_name=canvas_name,
comment_id=comment_id,
limit=limit,
cursor=cursor,
content_comment_id=content_comment_id,
content_offset=content_offset,
)
except InvalidTaskCommentCursor:
raise ValueError("Invalid canvas comment cursor") from None
def retrieve_task_comment(
*,
team_id: int,
task_id: UUID,
user_id: int | None,
comment_id: UUID,
limit: int,
cursor: str | None,
content_comment_id: UUID | None,
content_offset: int,
) -> contracts.TaskCommentDetailDTO | None:
from products.tasks.backend.logic.services.task_comments import InvalidTaskCommentCursor, retrieve_comment
try:
return retrieve_comment(
team_id=team_id,
task_id=task_id,
user_id=user_id,
comment_id=comment_id,
limit=limit,
cursor=cursor,
content_comment_id=content_comment_id,
content_offset=content_offset,
)
except InvalidTaskCommentCursor:
raise ValueError("Invalid task comment cursor") from None
def list_mentions(
team_id: int, user_id: int | None, *, since: datetime | None = None, limit: int = 100
) -> list[contracts.TaskMentionDTO]:
"""Thread-message mentions of the requester across tasks they can see, newest first."""
if user_id is None:
return []
qs = TaskThreadMessageMention.objects.filter(
team_id=team_id,
mentioned_user_id=user_id,
# task__in keeps the visibility rules single-sourced in _visible_task_qs.
task__in=_visible_task_qs(team_id, user_id, for_list=True),
# Legacy turn_complete rows are hidden from threads (see list_thread_messages),
# so their indexed mentions must not surface notifications pointing at them.
).exclude(message__event="turn_complete")
qs = qs.exclude(Task.scout_experiment_q(relation="task"))
if since is not None:
qs = qs.filter(created_at__gt=since)
mentions = qs.select_related("message__author", "task__channel").order_by("-created_at")[:limit]
return [
contracts.TaskMentionDTO(
id=mention.id,
message_id=mention.message_id,
task_id=mention.task_id,
task_title=mention.task.title,
channel_id=mention.task.channel_id,
channel_name=mention.task.channel.name if mention.task.channel else None,
content=mention.message.content,
created_at=mention.created_at,
author=_user_basic_info(mention.message.author if mention.message.author_id else None),
)
for mention in mentions
]
def project_thread_message_activity(message: TaskThreadMessage) -> None:
"""Project a new thread message onto the feed of everyone it concerns."""
recipient_ids = {recipient_id for recipient_id in (message.author_id, message.task.created_by_id) if recipient_id}
for recipient_id in recipient_ids:
TaskActivity.record(
team_id=message.team_id,
user_id=recipient_id,
task_id=message.task_id,
kind=TaskActivity.Kind.MESSAGE,
activity_at=message.created_at,
message_id=message.id,
actor_id=message.author_id,
)
def project_awaiting_input_activity(task_run: "TaskRun") -> None:
"""Flag the task creator's feed row when a run stops and needs them.
Called from ``push_dispatcher.notify_task_run_awaiting_input`` so every path that
decides a run is waiting (stream ingest, agent proxy callback, sandbox relay) projects
the same row. Deliberately outside the push feature flag and its Redis cooldown — the
in-app feed should update even where the mobile push is off.
"""
creator_id = task_run.task.created_by_id
if creator_id is None:
return
TaskActivity.record(
team_id=task_run.task.team_id,
user_id=creator_id,
task_id=task_run.task_id,
kind=TaskActivity.Kind.AWAITING_INPUT,
activity_at=django_timezone.now(),
)
def project_completed_activity(task_run: "TaskRun") -> None:
creator_id = task_run.task.created_by_id
if creator_id is None:
return
TaskActivity.record(
team_id=task_run.task.team_id,
user_id=creator_id,
task_id=task_run.task_id,
kind=TaskActivity.Kind.COMPLETED,
activity_at=task_run.completed_at or django_timezone.now(),
)
# A scout runs headless on a schedule, under an acting user resolved from the scout skill's
# author rather than from whoever asked for the run. Its task therefore carries a real person
# as `created_by`, so every projected row lands in a feed that person never asked for. Scout
# output belongs in the Signals inbox instead.
ACTIVITY_FEED_EXCLUDED_ORIGIN_PRODUCTS = (Task.OriginProduct.SIGNALS_SCOUT,)
def _activity_visible_task_qs(team_id: int, user_id: int) -> QuerySet[Task]:
return (
_visible_task_qs(team_id, user_id, for_list=True)
.filter(internal=False, archived=False)
.exclude(origin_product__in=ACTIVITY_FEED_EXCLUDED_ORIGIN_PRODUCTS)
)
def _task_activity_qs(team_id: int, user_id: int) -> QuerySet[TaskActivity]:
"""The requester's feed rows, gated to tasks they can still see.
Rows outlive visibility changes (a task moving to a private channel, say), so the
visibility gate belongs on read rather than being enforced when projecting.
"""
visible_tasks = _activity_visible_task_qs(team_id, user_id)
return TaskActivity.objects.for_team(team_id).filter(user_id=user_id, task__in=visible_tasks)
def _visible_activity_canvas_ids(team_id: int, user_id: int) -> set[str]:
"""Ids of the visible canvases among those the requester's comment activity names."""
from products.canvas.backend.facade import (
access as canvas_access, # noqa: PLC0415 — keeps canvas off django.setup()
)
# Only the canvases in the requester's own feed are candidates, so the lookup
# stays bounded by their activity and not by every canvas in the team.
item_ids = (
TaskCommentActivity.objects.for_team(team_id)
.filter(user_id=user_id, comment__deleted=False, comment__scope__in=CANVAS_COMMENT_SCOPES)
.values_list("comment__item_id", flat=True)
.distinct()
)
return canvas_access.live_visible_canvas_ids(team_id, user_id, [item_id for item_id in item_ids if item_id])
def _comment_activity_qs(
team_id: int, user_id: int, visible_canvas_ids: set[str] | None = None
) -> QuerySet[TaskCommentActivity]:
visible_tasks = _activity_visible_task_qs(team_id, user_id)
if visible_canvas_ids is None:
visible_canvas_ids = _visible_activity_canvas_ids(team_id, user_id)
return (
TaskCommentActivity.objects.for_team(team_id)
.filter(user_id=user_id, comment__deleted=False)
.filter(
Q(comment__scope__in=CANVAS_COMMENT_SCOPES, comment__item_id__in=visible_canvas_ids)
| (~Q(comment__scope__in=CANVAS_COMMENT_SCOPES) & Q(task__in=visible_tasks))
)
)
def _visible_canvases_by_id(
team_id: int, user_id: int, comment_rows: Sequence[TaskCommentActivity]
) -> dict[str, "CanvasSummary"]:
from products.canvas.backend.facade import (
access as canvas_access, # noqa: PLC0415 — keeps canvas off django.setup()
)
canvas_ids: list[UUID] = []
for row in comment_rows:
if row.comment.scope not in CANVAS_COMMENT_SCOPES:
continue
try:
canvas_ids.append(UUID(row.comment.item_id))
except ValueError:
continue
return canvas_access.visible_canvas_summaries(team_id=team_id, user_id=user_id, canvas_ids=canvas_ids)
@frozen
class _ActivityTaskDetails:
title: str
channel_id: UUID | None
channel_name: str | None
def _activity_task_details(
row: TaskActivity | TaskCommentActivity, canvases_by_id: dict[str, "CanvasSummary"]
) -> _ActivityTaskDetails:
if isinstance(row, TaskCommentActivity) and row.comment.scope in CANVAS_COMMENT_SCOPES and row.comment.item_id:
canvas = canvases_by_id.get(row.comment.item_id)
if canvas is not None:
return _ActivityTaskDetails(
title=canvas.name, channel_id=canvas.channel_id, channel_name=canvas.channel_name
)
if row.task is None:
return _ActivityTaskDetails(title="", channel_id=None, channel_name=None)
return _ActivityTaskDetails(
title=row.task.title,
channel_id=row.task.channel_id,
channel_name=row.task.channel.name if row.task.channel else None,
)
def count_unread_task_activity(team_id: int, user_id: int | None) -> int:
"""Unread tasks across the requester's whole feed. Backs the sidebar badge."""
if user_id is None:
return 0
return _count_unread_activity(team_id, user_id, _visible_activity_canvas_ids(team_id, user_id))
def _count_unread_activity(team_id: int, user_id: int, visible_canvas_ids: set[str]) -> int:
return (
_task_activity_qs(team_id, user_id).filter(read_at__isnull=True).count()
+ _comment_activity_qs(team_id, user_id, visible_canvas_ids).filter(read_at__isnull=True).count()
)
def list_task_activity(
team_id: int,
user_id: int | None,
*,
limit: int = 100,
before: datetime | None = None,
before_id: UUID | None = None,
) -> contracts.TaskActivityPageDTO:
"""The requester's task and comment activity, newest first.
``unread_count`` counts every unread row the requester can see, not just the ones in
this page, so the sidebar badge stays honest past ``limit``.
"""
if user_id is None:
return contracts.TaskActivityPageDTO(results=[], unread_count=0)
task_qs = _task_activity_qs(team_id, user_id)
visible_canvas_ids = _visible_activity_canvas_ids(team_id, user_id)
comment_qs = _comment_activity_qs(team_id, user_id, visible_canvas_ids)
if before is not None and before_id is not None:
cursor = Q(activity_at__lt=before) | Q(activity_at=before, id__lt=before_id)
task_qs = task_qs.filter(cursor)
comment_qs = comment_qs.filter(cursor)
task_rows = task_qs.select_related("task__channel", "message__author").order_by("-activity_at", "-id")[: limit + 1]
comment_rows = list(
comment_qs.select_related("task__channel", "comment__created_by").order_by("-activity_at", "-id")[: limit + 1]
)
canvases_by_id = _visible_canvases_by_id(team_id, user_id, comment_rows)
comment_rows = [
row
for row in comment_rows
if row.comment.scope not in CANVAS_COMMENT_SCOPES or row.comment.item_id in canvases_by_id
]
activity_rows: list[TaskActivity | TaskCommentActivity] = [*task_rows, *comment_rows]
rows: list[TaskActivity | TaskCommentActivity] = sorted(
activity_rows,
key=lambda row: (row.activity_at, row.id),
reverse=True,
)[: limit + 1]
has_more = len(rows) > limit
rows = rows[:limit]
next_row = rows[-1] if has_more else None
return contracts.TaskActivityPageDTO(
results=[
contracts.TaskActivityDTO(
id=row.id,
task_id=row.task_id,
task_title=task_details.title,
channel_id=task_details.channel_id,
channel_name=task_details.channel_name,
activity_at=row.activity_at,
activity_kind=row.kind,
snippet=_bounded_activity_snippet(
(row.comment.content or "" if row.comment else "")
if isinstance(row, TaskCommentActivity)
else (row.message.content if row.message else "")
),
latest_author=_user_basic_info(
row.comment.created_by
if isinstance(row, TaskCommentActivity)
else (row.message.author if row.message and row.message.author_id else None)
),
latest_message_id=None if isinstance(row, TaskCommentActivity) else row.message_id,
latest_comment_id=row.root_comment_id if isinstance(row, TaskCommentActivity) else None,
latest_comment_scope=row.comment.scope if isinstance(row, TaskCommentActivity) else None,
latest_comment_item_id=row.comment.item_id if isinstance(row, TaskCommentActivity) else None,
is_unread=row.read_at is None,
)
for row in rows
for task_details in [_activity_task_details(row, canvases_by_id)]
],
unread_count=_count_unread_activity(team_id, user_id, visible_canvas_ids),
next_before=next_row.activity_at if next_row else None,
next_before_id=next_row.id if next_row else None,
)
def _bounded_activity_snippet(content: str, limit: int = 1024) -> str:
return content.encode("utf-8")[:limit].decode("utf-8", errors="ignore")
def mark_task_activity_read(
team_id: int,
user_id: int | None,
activities: Sequence[tuple[UUID | None, datetime, UUID | None]],
) -> int:
"""Mark feed rows read only when their latest activity was visible to the requester."""
if user_id is None or not activities:
return 0
activity_versions = Q()
comment_activity_ids: list[UUID] = []
for task_id, seen_before, comment_activity_id in activities:
if comment_activity_id:
comment_activity_ids.append(comment_activity_id)
elif task_id:
activity_versions |= Q(task_id=task_id, activity_at__lte=seen_before)
task_rows = 0
if activity_versions:
task_rows = (
TaskActivity.objects.for_team(team_id)
.filter(user_id=user_id, read_at__isnull=True)
.filter(activity_versions)
.update(read_at=django_timezone.now())
)
comment_rows = (
TaskCommentActivity.objects.for_team(team_id)
.filter(
user_id=user_id,
id__in=comment_activity_ids,
read_at__isnull=True,
)
.update(read_at=django_timezone.now())
)
return task_rows + comment_rows
def delete_thread_message(message_id: str | UUID, task_id: str | UUID, team_id: int, user_id: int | None) -> str:
"""Delete own thread message. Returns ``ok`` / ``not_found`` / ``forbidden``."""
message = TaskThreadMessage.objects.filter(id=message_id, task_id=task_id, team_id=team_id).first()
if message is None or _visible_task(task_id, team_id, user_id) is None:
return "not_found"
if message.author_id != user_id:
return "forbidden"
message.delete()
return "ok"
def forward_thread_message(
message_id: str | UUID, task_id: str | UUID, team_id: int, user_id: int | None
) -> tuple[str, contracts.TaskThreadMessageDTO | None]:
"""Send a thread message to the task's agent. Task-author only.
Returns ``(kind, dto)`` where kind is ``ok`` / ``not_found`` / ``forbidden`` /
``already_forwarded`` / ``no_run`` / ``signal_failed``.
"""
task = _visible_task(task_id, team_id, user_id)
if task is None:
return "not_found", None
if task.created_by_id != user_id:
return "forbidden", None
# Lock the message row so concurrent forwards of the same message can't
# both pass the forwarded_to_agent_at check and double-signal the agent.
with transaction.atomic():
# of=("self",) locks only the message row: FOR UPDATE cannot span the nullable
# outer joins that select_related on author/forwarded_by introduces.
message = (
TaskThreadMessage.objects.select_for_update(of=("self",))
.select_related("author", "forwarded_by")
.filter(id=message_id, task_id=task_id, team_id=team_id)
.first()
)
if message is None:
return "not_found", None
if message.forwarded_to_agent_at is not None:
return "already_forwarded", _thread_message_to_dto(message)
run = task.latest_run
if run is None or run.status in (TaskRun.Status.COMPLETED, TaskRun.Status.FAILED, TaskRun.Status.CANCELLED):
return "no_run", None
author = message.author
author_name = (author.get_full_name() or author.email) if author else "A teammate"
content = f"[Thread comment from {author_name}] {message.content}"
signal_result = signal_task_run_user_message(
run.id, task.id, team_id, content=content, artifact_ids=[], actor_user_id=user_id
)
if not signal_result:
return "signal_failed", None
message.forwarded_to_agent_at = django_timezone.now()
message.forwarded_by_id = user_id
message.forwarded_run = run
message.save(update_fields=["forwarded_to_agent_at", "forwarded_by", "forwarded_run"])
return "ok", _thread_message_to_dto(message)
# Threads are a Channels (project-bluebird) surface, so agent-authored thread
# updates are gated on the same flag — evaluated for the task creator.
AGENT_THREAD_UPDATES_FLAG = "project-bluebird"
def _create_agent_thread_message(task: Task, content: str, *, event: str, payload: dict | None = None) -> None:
"""Write an agent-authored thread message and index its mentions.
``content`` is the rendered text (older clients show it as-is); ``event`` +
``payload`` are the structured record, mirroring ChannelFeedMessage, that
lets clients render agent rows natively and dedupe them against live views.
"""
# for_team: callers include non-request contexts (temporal relay) where the
# fail-closed manager has no team scope.
message = TaskThreadMessage.objects.for_team(task.team_id).create(
team_id=task.team_id,
task_id=task.id,
author_id=None,
author_kind=TaskThreadMessage.AuthorKind.AGENT,
event=event,
payload=payload or {},
content=content,
)
try:
# A projection failure must not roll back the caller's dedup transaction with
# the announcement in it; the savepoint contains a database error.
with transaction.atomic():
project_thread_message_activity(message)
except Exception:
logger.exception("Failed to project thread message activity", extra={"message_id": str(message.id)})
try:
mentioned_user_ids = resolve_mentioned_user_ids(
User, message.content, team_id=message.team_id, author_id=message.author_id
)
_index_thread_message_mentions(message, mentioned_user_ids)
except Exception:
logger.exception("Failed to index thread message mentions", extra={"message_id": str(message.id)})
def _agent_thread_updates_enabled(creator: User | None) -> bool:
"""Fail closed: no creator to key the flag on, or a flag-service error, means no post."""
if creator is None:
return False
# Local dev rarely has the server-side flag client wired up, and failing
# closed there silently drops every agent thread update (PR and canvas
# announcements vanish from task threads with nothing in the logs).
if settings.DEBUG:
return True
distinct_id = creator.distinct_id or f"user_{creator.id}"
try:
return bool(
posthoganalytics.feature_enabled(AGENT_THREAD_UPDATES_FLAG, distinct_id, send_feature_flag_events=False)
)
except Exception:
logger.warning("Agent thread update flag check failed", extra={"user_id": creator.id}, exc_info=True)
return False
def _commit_push_head_sha(output: object) -> str:
if not isinstance(output, dict) or not isinstance(output.get("commit_push"), dict):
return ""
commits = output["commit_push"].get("commits")
if not isinstance(commits, list) or not commits or not isinstance(commits[-1], dict):
return ""
sha = commits[-1].get("sha")
return sha[:64] if isinstance(sha, str) else ""
def post_commits_pushed_thread_update(run: TaskRun, push: dict) -> None:
try:
head_sha = _commit_push_head_sha({"commit_push": push})
if not head_sha:
return
task = Task.objects.select_related("created_by").filter(id=run.task_id, team_id=run.team_id).first()
if task is None or not _agent_thread_updates_enabled(task.created_by):
return
raw_commits = push.get("commits")
if not isinstance(raw_commits, list):
return
commits = [
{
"sha": str(commit.get("sha") or "")[:64],
"subject": str(commit.get("subject") or "")[:120],
"url": str(commit.get("url") or "")[:2048],
}
for commit in raw_commits[-10:]
if isinstance(commit, dict) and commit.get("sha")
]
if not commits:
return
with transaction.atomic():
Task.objects.select_for_update().filter(id=task.id).first()
if (
TaskThreadMessage.objects.for_team(task.team_id)
.filter(task_id=task.id, event="commits_pushed", payload__head_sha=head_sha)
.exists()
):
return
# Branch is caller-controlled and flows into rendered markdown content
# and the server-side mention scanner. Strip the bracket and newline
# characters that would otherwise forge a [label](url) link, a
#  image, or an @[name](email) mention (the canvas-name and
# PR-URL guards below sanitize their equivalents for the same reason).
branch = re.sub(r"[\[\]\n]", " ", str(push.get("branch") or "")).strip()[:255]
count = len(raw_commits)
content = f"{count} commit{'s' if count != 1 else ''} pushed"
_create_agent_thread_message(
task,
f"{content} to {branch}" if branch else content,
event="commits_pushed",
payload={
"run_id": str(run.id),
"branch": branch,
"repository": str(push.get("repository") or "")[:255],
"commits": commits,
"total": count,
"head_sha": head_sha,
},
)
except Exception:
logger.exception("Failed to post commits-pushed thread update", extra={"task_id": str(run.task_id)})
def _comment_target_name(task: Task, *, scope: str, item_id: str | None) -> str | None:
"""The commented artifact's display name for the row label; None on the task's own scope."""
if scope != "task_artifact" or not item_id:
return None
try:
name = (
TaskArtifact.objects.for_team(task.team_id)
.filter(task_id=task.id, id=item_id)
.values_list("name", flat=True)
.first()
)
except (ValueError, DjangoValidationError):
name = None
if not name:
run = (
TaskRun.objects.filter(team_id=task.team_id, task_id=task.id, artifacts__contains=[{"id": item_id}])
.values_list("artifacts", flat=True)
.first()
)
name = next((entry.get("name") for entry in run or [] if entry.get("id") == item_id), None)
return str(name)[:255] if name else None
def post_comment_thread_update(*, team_id: int, comment_id: UUID) -> None:
"""Draw a comment on the task timeline: identity-only payload, the commenter as author.
Root comments and resolve/reopen replies each get a row; plain replies stay in the
Comments tab so a busy thread cannot flood the timeline.
"""
from posthog.models.comment import Comment # noqa: PLC0415 — keeps the comments app off the api import path
from products.tasks.backend.logic.services.comment_activity import comment_task_id # noqa: PLC0415
try:
comment = Comment.objects.filter(team_id=team_id, id=comment_id, deleted=False).first()
if comment is None or comment.created_by_id is None:
return
context = comment.item_context if isinstance(comment.item_context, dict) else {}
thread_state = context.get("threadState")
if comment.source_comment_id and thread_state in ("resolved", "open"):
event = "comment_state_changed"
elif comment.source_comment_id:
return
else:
event = "comment_added"
task_id = comment_task_id(comment)
if task_id is None:
return
task = Task.objects.select_related("created_by").filter(id=task_id, team_id=team_id).first()
if task is None or not _agent_thread_updates_enabled(task.created_by):
return
payload: dict = {
"comment_id": str(comment.id),
"root_comment_id": str(comment.source_comment_id or comment.id),
"scope": comment.scope,
"item_id": str(comment.item_id) if comment.item_id else None,
"target_name": _comment_target_name(task, scope=comment.scope, item_id=comment.item_id),
}
if event == "comment_state_changed":
payload["state"] = thread_state
content = "Resolved a comment thread" if thread_state == "resolved" else "Reopened a comment thread"
else:
content = "Commented"
with transaction.atomic():
Task.objects.select_for_update().filter(id=task.id).first()
if (
TaskThreadMessage.objects.for_team(task.team_id)
.filter(task_id=task.id, event=event, payload__comment_id=str(comment.id))
.exists()
):
return
# Not _create_agent_thread_message: the commenter is the author, and the
# comment path already projected activity and indexed mentions.
TaskThreadMessage.objects.for_team(task.team_id).create(
team_id=task.team_id,
task_id=task.id,
author_id=comment.created_by_id,
author_kind=TaskThreadMessage.AuthorKind.HUMAN,
event=event,
payload=payload,
content=content,
)
except Exception:
logger.exception("Failed to post comment thread update", extra={"comment_id": str(comment_id)})
def _announce_agent_artifact_uploads(run: TaskRun, new_entries: list[dict], manifest: list[dict]) -> None:
"""Announce files the agent delivered as task outputs.
The manifest also holds internal state such as skill bundles. Those files support the
run but are not deliverables for the timeline.
Manifest entries carry no version, so same-named output entries determine whether
an upload created or revised a file. The artifact id deduplicates retried uploads.
"""
output_entries = [entry for entry in new_entries if entry.get("type") == "output"]
new_output_ids = {entry.get("id") for entry in output_entries}
announced_in_batch: dict[str, int] = {}
for entry in output_entries:
name = entry.get("name")
prior_versions = sum(
1
for other in manifest
if other.get("type") == "output" and other.get("name") == name and other.get("id") not in new_output_ids
) + announced_in_batch.get(name or "", 0)
announced_in_batch[name or ""] = announced_in_batch.get(name or "", 0) + 1
post_artifact_thread_update(
run,
{
"id": entry.get("id"),
"name": name,
"artifact_type": entry.get("type"),
"current_version": prior_versions + 1,
},
revised=prior_versions > 0,
)
def post_artifact_thread_update(run: TaskRun, artifact: dict, *, revised: bool) -> None:
try:
artifact_id = str(artifact.get("id") or "")
# Caller-controlled, rendered as markdown, and scanned for mentions: strip
# link/mention syntax like the commits-pushed branch field.
name = re.sub(r"[\[\]\n]", " ", str(artifact.get("name") or "")).strip()[:255]
if not artifact_id or not name:
return
raw_version = artifact.get("current_version")
version = raw_version if isinstance(raw_version, int) else 1
task = Task.objects.select_related("created_by").filter(id=run.task_id, team_id=run.team_id).first()
if task is None or not _agent_thread_updates_enabled(task.created_by):
return
reference_type = str(artifact.get("reference_type") or "")[:64]
object_kind = str(artifact.get("object_kind") or "")[:64]
event = "artifact_revised" if revised else "artifact_created"
with transaction.atomic():
Task.objects.select_for_update().filter(id=task.id).first()
if (
TaskThreadMessage.objects.for_team(task.team_id)
.filter(task_id=task.id, event=event, payload__artifact_id=artifact_id, payload__version=version)
.exists()
):
return
verb = "Revised" if revised else "Added" if reference_type == "posthog_object" else "Created"
payload = {
"run_id": str(run.id),
"artifact_id": artifact_id,
"name": name,
"artifact_type": str(artifact.get("artifact_type") or "")[:64],
"version": version,
}
if reference_type:
payload["reference_type"] = reference_type
if object_kind:
payload["object_kind"] = object_kind
_create_agent_thread_message(task, f"{verb} {name}", event=event, payload=payload)
except Exception:
logger.exception("Failed to post artifact thread update", extra={"task_id": str(run.task_id)})
def _thread_safe_canvas_name(canvas_name: str) -> str:
# Brackets and newlines in the name would break the [label](url) token.
return re.sub(r"[\[\]\n]", " ", canvas_name).strip() or "Canvas"
def post_canvas_created_thread_update(
task_id: str | UUID, team_id: int, *, acting_user_id: int | None, canvas_name: str, canvas_url: str | None
) -> None:
"""Announce a freshly created canvas in the generating task's thread.
Posts "[name](url) has been created" as an agent message. Called on a canvas's
first publish only — the caller owns that once-guard. ``acting_user_id`` must be
the task's creator: the sandbox publishes with the creator's credentials, so this
binds the attributed task to the caller's identity — a same-team caller can't
plant agent messages in someone else's task thread by naming its id. Best-effort
and never raises: the publish must not fail because its announcement couldn't
be written.
"""
try:
task = Task.objects.select_related("created_by").filter(id=task_id, team_id=team_id).first()
if task is None or task.created_by_id is None or task.created_by_id != acting_user_id:
return
if not _agent_thread_updates_enabled(task.created_by):
return
name = _thread_safe_canvas_name(canvas_name)
content = f"[{name}]({canvas_url}) has been created" if canvas_url else f"{name} has been created"
_create_agent_thread_message(
task,
content,
event="canvas_created",
payload={"canvas_name": name, "canvas_url": canvas_url},
)
except Exception:
logger.exception("Failed to post canvas-created thread update", extra={"task_id": str(task_id)})
def post_canvas_error_thread_update(
task_id: str | UUID,
team_id: int,
*,
canvas_id: str,
canvas_name: str,
build_id: str,
source_version_id: str | None,
error_type: str,
origin: str,
error_codes: list[str] | None = None,
) -> str:
"""File a canvas failure report (``event="canvas_error_reported"``) in the authoring task's thread.
``error_type``/``error_codes`` must already be validated identifiers — the canvas
backend owns that sanitization because everything here lands in agent-visible text.
The task id is resolved server-side from the canvas record, never caller-named, so
a teammate can't plant reports in an unrelated task's thread. Dedupes per
``(build_id, error_type)`` under the task row lock, mirroring ``pr_created``.
Returns ``filed`` / ``duplicate`` / ``skipped``; never raises.
"""
try:
task = Task.objects.select_related("created_by").filter(id=task_id, team_id=team_id).first()
if task is None or not _agent_thread_updates_enabled(task.created_by):
return "skipped"
with transaction.atomic():
Task.objects.select_for_update().filter(id=task.id).first()
if (
TaskThreadMessage.objects.for_team(task.team_id)
.filter(
task_id=task.id,
event="canvas_error_reported",
payload__build_id=build_id,
payload__error_type=error_type,
)
.exists()
):
return "duplicate"
name = _thread_safe_canvas_name(canvas_name)
if origin == "build":
codes = ", ".join(error_codes or []) or "unknown"
content = f'Canvas "{name}" build failed ({codes})'
else:
content = f'Canvas "{name}" hit a runtime error ({error_type}) in a rendering session'
_create_agent_thread_message(
task,
content,
event="canvas_error_reported",
payload={
"canvas_id": canvas_id,
"canvas_name": name,
"build_id": build_id,
"source_version_id": source_version_id,
"error_type": error_type,
"origin": origin,
"error_codes": error_codes or [],
},
)
return "filed"
except Exception:
logger.exception("Failed to post canvas-error thread update", extra={"task_id": str(task_id)})
return "skipped"
def _canvas_fix_denial_outcome(reason: str) -> str:
"""Map a compute-quota denial to a canvas fix outcome.
Deactivation and quota exhaustion need different copy: a retry clears a spent
quota but never a deactivation.
"""
from products.tasks.backend.logic.services.compute_quota import ( # noqa: PLC0415
ORGANIZATION_DEACTIVATED_DENIAL_CODE,
)
return "organization_deactivated" if reason == ORGANIZATION_DEACTIVATED_DENIAL_CODE else "quota_exhausted"
def request_canvas_fix(task_id: str | UUID, team_id: int, *, prompt: str, acting_user_id: int | None) -> str:
"""Wake a task's agent to fix a canvas: signal the live run, else seed a fresh run with ``prompt``.
Creator-only, like every run-driving surface (``forward_thread_message``,
``task_control_q``): the dispatched run executes with the task creator's
credentials, so nobody else may start or steer it. The task row is locked
for the duration so overlapping fix requests serialize instead of each
creating a paid run. The fresh-run path creates the run inside the
transaction and dispatches its processing workflow on commit with
``skip_user_check``.
Returns ``signaled`` / ``new_run`` / ``already_queued`` / ``not_found`` /
``forbidden`` / ``quota_exhausted`` / ``organization_deactivated``.
"""
from products.tasks.backend.exceptions import (
ComputeBillingLimitError, # noqa: PLC0415 — keep temporalio off the api import path
)
from products.tasks.backend.logic.services.compute_quota import get_compute_quota_denial_reason # noqa: PLC0415
with transaction.atomic():
# of=("self",): FOR UPDATE cannot span the nullable created_by join.
task = (
Task.objects.select_for_update(of=("self",))
.select_related("team", "created_by")
.filter(id=task_id, team_id=team_id)
.first()
)
if task is None:
return "not_found"
if acting_user_id is None or task.created_by_id != acting_user_id:
return "forbidden"
if reason := get_compute_quota_denial_reason(task):
return _canvas_fix_denial_outcome(reason)
run = task.latest_run
if run is not None and not run.is_terminal:
try:
if signal_task_run_user_message(
run.id, task.id, team_id, content=prompt, artifact_ids=[], actor_user_id=acting_user_id
):
return "signaled"
except ComputeBillingLimitError as error:
return _canvas_fix_denial_outcome(error.reason)
if run.status == TaskRun.Status.QUEUED and (run.state or {}).get("pending_user_message"):
# A queued, prompt-seeded run whose workflow hasn't registered yet
# is a fix run a just-committed request dispatched (creation is
# serialized on this row lock). Another run would double-bill.
return "already_queued"
# The workflow is gone despite the non-terminal row (evicted or stale); fall
# through to a fresh run rather than reporting a dead end.
task_run = task.create_run(mode="background", extra_state={"pending_user_message": prompt})
from products.tasks.backend.logic.services.workflow_dispatch import ( # noqa: PLC0415
WorkflowDispatchOptions,
enqueue_or_start_workflow,
)
enqueue_or_start_workflow(
task_run,
options=WorkflowDispatchOptions(user_id=task.created_by_id, skip_user_check=True),
)
return "new_run"
def request_canvas_change(
task_id: str | UUID,
team_id: int,
*,
prompt: str,
viewer_prompt: str,
acting_user_id: int | None,
) -> str:
"""Dispatch a creator's canvas request, or file a teammate's request for review."""
with transaction.atomic():
task = Task.objects.select_for_update().filter(id=task_id, team_id=team_id).first()
if task is None:
return "not_found"
if acting_user_id is None:
return "not_found"
is_creator = task.created_by_id == acting_user_id
if not is_creator:
# A teammate can reach this through a canvas they can see while the authoring
# task is deleted or filed in a space they can't — the thread message is then
# dropped, so surface the miss instead of reporting a delivery that didn't happen.
filed = create_thread_message(
task_id,
team_id,
acting_user_id,
content=f"Requested from the canvas:\n\n{viewer_prompt}",
)
return "reported" if filed is not None else "not_found"
outcome = request_canvas_fix(task_id, team_id, prompt=prompt, acting_user_id=acting_user_id)
# already_queued is a deduplicated repeat: the request that queued the run
# already wrote this entry, so writing another would double the record.
if outcome in {"signaled", "new_run"}:
create_thread_message(task_id, team_id, acting_user_id, content="Run requested from the canvas")
return outcome
_GITHUB_PR_PATH_PATTERN = re.compile(r"/([^/]+)/([^/]+)/pull/(\d+)/?", re.IGNORECASE)
# Characters that could break out of a markdown [label](url) token or smuggle
# extra markdown into the rendered thread message.
_PR_URL_UNSAFE_CHARS = set(" \t\n\r()[]<>\"'`\\")
_PR_URL_MAX_LENGTH = 2048
def _is_safe_pr_url(pr_url: str) -> bool:
"""Whether ``pr_url`` is a plain http(s) URL safe to embed in a markdown link.
``pr_url`` originates from task-run output APIs, so it is caller-controlled.
Real PR URLs never contain whitespace, quotes, brackets, or parentheses;
anything that does is rejected rather than escaped.
"""
if not pr_url or len(pr_url) > _PR_URL_MAX_LENGTH or any(char in _PR_URL_UNSAFE_CHARS for char in pr_url):
return False
parsed = urlparse(pr_url)
return parsed.scheme in ("http", "https") and bool(parsed.netloc)
def _pr_display_label(pr_url: str) -> str:
parsed = urlparse(pr_url)
if parsed.hostname is None or parsed.hostname.lower() != "github.com":
return pr_url
match = _GITHUB_PR_PATH_PATTERN.fullmatch(parsed.path)
if match:
owner, repo, number = match.groups()
return f"{owner}/{repo}#{number}"
return pr_url
def post_pr_created_thread_update(run: TaskRun, pr_url: str) -> None:
"""Announce a run's freshly opened pull request in its task's thread.
Posts "[owner/repo#N](url) has been opened" as an agent artifact message
(``event="pr_created"``). Both the agent-output path and the GitHub webhook
backstop can observe the same PR, so the announcement dedupes on the task's
existing ``pr_created`` rows for this URL. Best-effort and never raises —
recording the PR must not fail because its announcement couldn't be written.
"""
try:
if not _is_safe_pr_url(pr_url):
logger.info("pr_created thread update skipped", extra={"task_id": str(run.task_id), "reason": "unsafe_url"})
return
# Unlike turn_complete's old channel guard, artifact rows post for
# channel-less tasks too: every task has a thread panel.
task = Task.objects.select_related("created_by").filter(id=run.task_id, team_id=run.team_id).first()
if task is None:
return
if task.created_by is None or not _agent_thread_updates_enabled(task.created_by):
logger.info(
"pr_created thread update skipped",
extra={"task_id": str(task.id), "reason": "no_creator" if task.created_by is None else "flag_off"},
)
return
# The agent-output path and the webhook backstop can race on the same PR;
# locking the task row makes the dedupe check-and-create atomic across them.
with transaction.atomic():
Task.objects.select_for_update().filter(id=task.id).first()
if (
TaskThreadMessage.objects.for_team(task.team_id)
.filter(task_id=task.id, event="pr_created", payload__pr_url=pr_url)
.exists()
):
return
label = _pr_display_label(pr_url)
_create_agent_thread_message(
task,
f"[{label}]({pr_url}) has been opened",
event="pr_created",
payload={"pr_url": pr_url},
)
except Exception:
logger.exception("Failed to post pr-created thread update", extra={"task_id": str(run.task_id)})
# --- Inbound GitHub App deliveries (entered from backend/webhook_consumers.py) ---
def accept_github_pull_request(delivery: WebhookDelivery) -> None:
"""The PR backstop that records a pull request the agent output never reported."""
# Deferred to keep the GitHub client off the facade import path.
from products.tasks.backend.webhooks import handle_pull_request_event # noqa: PLC0415
handle_pull_request_event(dict(delivery.payload))
def accept_github_pull_request_review(delivery: WebhookDelivery) -> None:
"""A review on a PR a task opened, which can resume the run that is waiting on it."""
# Deferred to keep the GitHub client off the facade import path.
from products.tasks.backend.webhooks import handle_pull_request_review_event # noqa: PLC0415
handle_pull_request_review_event(dict(delivery.payload))
def is_current_task_run_actor(team_id: int, run_id: UUID, user_id: int) -> bool:
from products.tasks.backend.logic.services.run_actor import ( # noqa: PLC0415
get_task_run_actor_user,
user_has_current_team_access,
)
run = TaskRun.objects.select_related("task__created_by", "team__organization").get(id=run_id, team_id=team_id)
actor = get_task_run_actor_user(run.task, run.state, allow_task_creator_fallback=False)
return actor is not None and actor.id == user_id and user_has_current_team_access(actor, run.team)
def record_task_mobile_pickup(*, task_id: str, team_id: int, user_id: int | None) -> None:
from products.tasks.backend.mobile_push import (
record_mobile_pickup, # noqa: PLC0415 — keep notification helpers off the facade import path
)
if user_id is None:
return
try:
record_mobile_pickup(task_id=task_id, team_id=team_id, user_id=user_id)
except Exception:
logger.exception(
"mobile_push.pickup_failed", extra={"task_id": task_id, "team_id": team_id, "user_id": user_id}
)
def task_mobile_push_taken_over(*, task_id: str, team_id: int, user_id: int) -> bool:
from products.tasks.backend.mobile_push import (
mobile_push_user_ids, # noqa: PLC0415 — keep notification helpers off the facade import path
)
task = Task.objects.filter(id=task_id, team_id=team_id).only("state").first()
return task is not None and user_id in mobile_push_user_ids(task)
def task_mobile_push_delivery_allowed(*, task_id: str, team_id: int, user_id: int) -> bool:
from products.tasks.backend.mobile_push import (
task_mobile_push_eligible, # noqa: PLC0415 — keep notification helpers off the facade import path
)
task = (
Task.objects.filter(id=task_id, team_id=team_id, deleted=False)
.filter(task_visibility_q(user_id))
.select_related("team")
.first()
)
if task is None or not task_mobile_push_eligible(task, user_id):
return False
user = User.objects.filter(id=user_id, is_active=True).first()
return user is not None and UserAccessControl(user=user, team=task.team).check_access_level_for_resource(
"task", "viewer"
)
def task_mobile_push_user_ids(*, task_id: str, team_id: int) -> set[int]:
from products.tasks.backend.mobile_push import (
mobile_push_user_ids, # noqa: PLC0415 — keep notification helpers off the facade import path
)
task = Task.objects.filter(id=task_id, team_id=team_id).only("state").first()
return mobile_push_user_ids(task) if task is not None else set()
def task_mobile_push_suppressed_token_ids(*, user_id: int, task_id: str, team_id: int) -> list[str]:
from products.tasks.backend.mobile_push import (
suppressed_push_token_ids_for_task, # noqa: PLC0415 — keep notification helpers off the facade import path
)
return suppressed_push_token_ids_for_task(user_id=user_id, task_id=task_id, team_id=team_id)
def enqueue_task_mobile_pr_outcome(
*, task_id: str, team_id: int, user_id: int, pr_url: str, kind: str, enqueue: Callable[[], None]
) -> bool:
from products.tasks.backend.mobile_push import (
enqueue_mobile_pr_outcome, # noqa: PLC0415 — keep notification helpers off the facade import path
)
return enqueue_mobile_pr_outcome(
task_id=task_id, team_id=team_id, user_id=user_id, pr_url=pr_url, kind=kind, enqueue=enqueue
)
def claim_mobile_push_cooldown(key: str, *, timeout_seconds: int) -> bool:
from products.tasks.backend.redis import get_tasks_cache # noqa: PLC0415 — keep redis off the api import path
return bool(get_tasks_cache().add(key, True, timeout=timeout_seconds))
def release_mobile_push_cooldown(key: str) -> None:
from products.tasks.backend.redis import get_tasks_cache # noqa: PLC0415 — keep redis off the api import path
get_tasks_cache().delete(key)