: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
from typing import Any
import pydantic
from asgiref.sync import async_to_sync, sync_to_async
from drf_spectacular.utils import extend_schema_field, extend_schema_serializer
from langgraph.graph.state import CompiledStateGraph
from rest_framework import serializers
from rest_framework_dataclasses.serializers import DataclassSerializer
from posthog.schema import ApprovalDecisionStatus
from posthog.api.shared import UserBasicSerializer
from posthog.dataclasses import frozen
from posthog.exceptions_capture import capture_exception
from products.posthog_ai.backend.models.assistant import Conversation
from products.tasks.backend.facade import api as tasks_facade
from products.tasks.backend.facade.contracts import TaskDetailDTO, TaskRunDetailDTO, TaskUserBasicInfo
from products.tasks.backend.facade.run_config import REASONING_EFFORTS, LLMProvider, RuntimeAdapter
from ee.hogai.artifacts.manager import ArtifactManager
from ee.hogai.chat_agent import AssistantGraph
from ee.hogai.research_agent.graph import ResearchAgentGraph
from ee.hogai.tool import ApprovalRequest, pending_approval_proposal_id
from ee.hogai.utils.helpers import should_output_assistant_message
from ee.hogai.utils.types import AssistantState
from ee.hogai.utils.types.composed import AssistantMaxGraphState
_conversation_fields = [
"id",
"status",
"title",
"topic",
"user",
"created_at",
"updated_at",
"type",
"is_internal",
"slack_thread_key",
"slack_workspace_domain",
]
CONVERSATION_TYPE_MAP: dict[
Conversation.Type, tuple[type[AssistantGraph | ResearchAgentGraph], type[AssistantMaxGraphState]]
] = {
Conversation.Type.ASSISTANT: (AssistantGraph, AssistantState),
Conversation.Type.TOOL_CALL: (AssistantGraph, AssistantState),
Conversation.Type.SLACK: (AssistantGraph, AssistantState),
Conversation.Type.DEEP_RESEARCH: (ResearchAgentGraph, AssistantState),
}
@frozen
class ConversationStateResult:
state: AssistantMaxGraphState | None
has_unsupported_content: bool
interrupt_payloads: dict[str, dict[str, Any]]
async def aget_conversation_state(
conversation: Conversation, team: Any, user: Any, *, raise_on_error: bool = False
) -> ConversationStateResult:
"""Compile the LangGraph graph, replay the checkpoint, and validate the typed state.
Single source of truth for the LangGraph history read path — both the conversation
serializer (history-load) and the conversation mirror (products/posthog_ai) call this so
the graph-compile + checkpoint-replay logic is never duplicated.
Returns a ConversationStateResult. `state` is None for born-sandbox
conversations (no checkpoint) and on any read/validation error — errors degrade gracefully
and are captured rather than raised so a bad checkpoint can't 500 a conversation load.
`raise_on_error` re-raises read errors instead, for a caller that retries (the copy activity);
unsupported content still comes back as a result, since a retry cannot fix it.
"""
# Born-sandbox conversations have no LangGraph checkpoint — skip the graph compile entirely.
# A conversation moved from LangGraph keeps its checkpoint, but its history is in the task's
# import run, which the thread renders from the run log; reading the checkpoint too would show
# every turn twice. Only a conversion that predates the mirror (no import run) still renders
# its legacy thread above the "history was converted" divider.
if conversation.agent_runtime == Conversation.AgentRuntime.SANDBOX:
empty = ConversationStateResult(state=None, has_unsupported_content=False, interrupt_payloads={})
if not await sync_to_async(conversation.checkpoints.exists)():
return empty
if conversation.task_id is not None and await sync_to_async(tasks_facade.get_imported_task_run)(
conversation.task_id, conversation.team_id
):
return empty
try:
graph_class, state_class = CONVERSATION_TYPE_MAP[conversation.type] # type: ignore[index]
graph: CompiledStateGraph = graph_class(team, user).compile_full_graph()
snapshot = await graph.aget_state({"configurable": {"thread_id": str(conversation.id), "checkpoint_ns": ""}})
state = state_class.model_validate(snapshot.values)
# Extract interrupt payloads from pending tasks — the single source of truth for payload data.
interrupt_payloads: dict[str, dict[str, Any]] = {}
for task in snapshot.tasks:
if task.result is not None:
continue
for interrupt in task.interrupts:
proposal_id = pending_approval_proposal_id(interrupt.value)
if proposal_id:
value = interrupt.value
interrupt_payloads[proposal_id] = (
value.model_dump() if isinstance(value, ApprovalRequest) else value
)
return ConversationStateResult(
state=state, has_unsupported_content=False, interrupt_payloads=interrupt_payloads
)
except pydantic.ValidationError as e:
capture_exception(
e,
additional_properties={
"tag": "max_ai",
"exception_type": "ValidationError",
"conversation_id": str(conversation.id),
},
)
return ConversationStateResult(state=None, has_unsupported_content=True, interrupt_payloads={})
except Exception as e:
if raise_on_error:
raise
# Broad exception handler to gracefully degrade UI instead of 500s.
# Captures all errors (context access, graph compilation, validation, etc.) to PostHog.
capture_exception(
e,
additional_properties={
"tag": "max_ai",
"exception_type": type(e).__name__,
"conversation_id": str(conversation.id),
},
)
return ConversationStateResult(state=None, has_unsupported_content=False, interrupt_payloads={})
class TaskUserBasicInfoSerializer(DataclassSerializer):
"""Response shape for a task creator, mirroring core ``UserBasicSerializer`` output."""
class Meta:
dataclass = TaskUserBasicInfo
class TaskRunArtifactResponseSerializer(serializers.Serializer):
id = serializers.CharField(required=False, help_text="Stable identifier for the artifact within this run")
name = serializers.CharField(help_text="Artifact file name")
type = serializers.CharField(help_text="Artifact classification, such as plan or output")
source = serializers.CharField( # type: ignore[assignment] # field literally named `source`; shadows base `Field.source`
required=False,
allow_blank=True,
help_text="Source of the artifact, such as agent_output or user_attachment",
)
size = serializers.IntegerField(required=False, help_text="Artifact size in bytes")
content_type = serializers.CharField(required=False, allow_blank=True, help_text="Optional MIME type")
storage_path = serializers.CharField(help_text="S3 object key for the artifact")
uploaded_at = serializers.CharField(help_text="Timestamp when the artifact was uploaded")
class TaskRunDetailSerializer(DataclassSerializer):
"""Detail response for the latest task run when a caller includes it."""
task = serializers.UUIDField(help_text="Parent task id this run belongs to.")
log_url = serializers.URLField(allow_null=True, required=False, help_text="Presigned S3 URL for log access.")
artifacts = TaskRunArtifactResponseSerializer(many=True, read_only=True)
runtime_adapter = serializers.ChoiceField(
choices=RuntimeAdapter.choices,
allow_null=True,
required=False,
help_text="Configured runtime adapter for this run, such as 'claude' or 'codex'.",
)
provider = serializers.ChoiceField(
choices=[provider.value for provider in LLMProvider],
allow_null=True,
required=False,
help_text="Configured LLM provider for this run, such as 'anthropic' or 'openai'.",
)
model = serializers.CharField(
allow_null=True, required=False, help_text="Configured LLM model identifier for this run."
)
reasoning_effort = serializers.ChoiceField(
choices=list(REASONING_EFFORTS),
allow_null=True,
required=False,
help_text="Configured reasoning effort for this run when the selected model supports it.",
)
class Meta:
dataclass = TaskRunDetailDTO
fields = [
"id",
"task",
"stage",
"branch",
"status",
"environment",
"runtime_adapter",
"provider",
"model",
"reasoning_effort",
"log_url",
"error_message",
"output",
"state",
"artifacts",
"created_at",
"updated_at",
"completed_at",
]
class TaskSerializer(DataclassSerializer):
"""Local serializer for the products/tasks task DTO exposed in conversation responses."""
latest_run = TaskRunDetailSerializer(allow_null=True, required=False, help_text="Latest run details for this task")
created_by = TaskUserBasicInfoSerializer(allow_null=True, required=False)
runtime = serializers.ChoiceField(
choices=tasks_facade.TaskRuntime.choices,
read_only=True,
help_text="Agent protocol and harness used for this task's runs.",
)
class Meta:
dataclass = TaskDetailDTO
fields = [
"id",
"task_number",
"slug",
"title",
"title_manually_set",
"description",
"origin_product",
"runtime",
"repository",
"github_integration",
"github_user_integration",
"signal_report",
"json_schema",
"internal",
"archived",
"archived_at",
"latest_run",
"created_at",
"updated_at",
"created_by",
"ci_prompt",
]
# Named explicitly: the inherited ``Meta.dataclass`` would otherwise emit this as a second
# ``TaskDetailDTO`` component, colliding with (and clobbering) the tasks product's nested-run shape.
@extend_schema_serializer(component_name="ConversationTask")
class ConversationTaskSerializer(TaskSerializer):
"""Conversation envelope variant: ``latest_run`` is just the latest run's id, not the nested
run detail. The frontend only needs the id to reconnect to sandbox logs, and emitting the id
avoids presigning a log URL per conversation. Task data follows the task's space visibility."""
latest_run = serializers.UUIDField( # type: ignore[assignment] # intentional narrowing of the base nested-run field to its id
source="latest_run_id",
allow_null=True,
read_only=True,
help_text="Id of the latest TaskRun; null when the task has no runs.",
)
class ConversationMinimalSerializer(serializers.ModelSerializer):
class Meta:
model = Conversation
# `task` is exposed here (not in `_conversation_fields`) so it stays out of the full
# serializer's field list, which already appends `task` itself — listing it twice
# would raise a DRF duplicate-field error.
fields = [*_conversation_fields, "task"]
read_only_fields = fields
user = UserBasicSerializer(read_only=True)
task = serializers.SerializerMethodField()
@extend_schema_field(ConversationTaskSerializer(allow_null=True))
def get_task(self, conversation: Conversation) -> dict[str, Any] | None:
if conversation.task_id is None:
return None
task_dtos = self.context.get("conversation_task_dtos_by_id")
if isinstance(task_dtos, dict):
task_dto: TaskDetailDTO | None = task_dtos.get(str(conversation.task_id))
else:
team = self.context["team"]
user = self.context["user"]
task_dto = tasks_facade.get_conversation_task_dtos([conversation.task_id], team.id, user.id).get(
conversation.task_id
)
if task_dto is None:
return None
return ConversationTaskSerializer(task_dto).data
class ConversationSerializer(ConversationMinimalSerializer):
class Meta:
model = Conversation
fields = [
*_conversation_fields,
"messages",
"has_unsupported_content",
"agent_mode",
"agent_runtime",
"is_sandbox",
"pending_approvals",
"task",
]
read_only_fields = fields
agent_runtime = serializers.ChoiceField(
choices=Conversation.AgentRuntime.choices,
read_only=True,
help_text=(
"Runtime that owns this conversation. 'langgraph' conversations return their messages "
"in the `messages` field. 'sandbox' conversations return an empty `messages` array and "
"load history from the products/tasks logs endpoint; a conversation copied into a task "
"carries its legacy thread in that task's import run. Only a conversion that predates "
"the copy still returns its legacy thread in `messages`."
),
)
messages = serializers.SerializerMethodField()
has_unsupported_content = serializers.SerializerMethodField()
agent_mode = serializers.SerializerMethodField()
is_sandbox = serializers.SerializerMethodField()
pending_approvals = serializers.SerializerMethodField()
def get_messages(self, conversation: Conversation) -> list[dict[str, Any]]:
# Sandbox conversations render their history from the task run logs (fetched via the
# products/tasks `logs/` endpoint), so `_get_cached_state` returns None and messages are [];
# the cached `messages_json` is intentionally ignored on this path. The one exception is a
# conversion that predates the mirror (see `aget_conversation_state`). LangGraph
# conversations use the cached `messages_json` when present, else compile + replay the
# checkpoint.
if conversation.agent_runtime == Conversation.AgentRuntime.SANDBOX:
return self._render_state_messages(self._get_cached_state(conversation).state)
if conversation.messages_json is not None:
return conversation.messages_json
return self._render_state_messages(self._get_cached_state(conversation).state)
def _render_state_messages(self, state: AssistantMaxGraphState | None) -> list[dict[str, Any]]:
if state is None:
return []
try:
team = self.context["team"]
user = self.context["user"]
artifact_manager = ArtifactManager(team, user)
enriched_messages = async_to_sync(artifact_manager.aenrich_messages)(list(state.messages))
return [message.model_dump() for message in enriched_messages if should_output_assistant_message(message)]
except Exception as e:
capture_exception(e)
return []
def get_has_unsupported_content(self, conversation: Conversation) -> bool:
return self._get_cached_state(conversation).has_unsupported_content
def get_agent_mode(self, conversation: Conversation) -> str | None:
result = self._get_cached_state(conversation)
if result.state:
return result.state.agent_mode_or_default
return None
def get_is_sandbox(self, conversation: Conversation) -> bool:
return conversation.agent_runtime == Conversation.AgentRuntime.SANDBOX
def get_pending_approvals(self, conversation: Conversation) -> list[dict[str, Any]]:
"""
Return pending approval cards as structured data.
Combines metadata from conversation.approval_decisions with payload from checkpoint
interrupts (single source of truth for payload data).
"""
cached_state = self._get_cached_state(conversation)
result: list[dict[str, Any]] = []
for proposal_id, decision_data in conversation.approval_decisions.items():
if not isinstance(decision_data, dict):
continue
tool_name = decision_data.get("tool_name")
preview = decision_data.get("preview")
decision_status = decision_data.get("decision_status")
if not tool_name or not preview or not decision_status:
continue
if (
decision_status == ApprovalDecisionStatus.PENDING
and cached_state.state is not None
and proposal_id not in cached_state.interrupt_payloads
):
decision_status = ApprovalDecisionStatus.AUTO_REJECTED
# Get payload from checkpoint interrupts (single source of truth)
payload = cached_state.interrupt_payloads.get(proposal_id, {}).get("payload", {})
result.append(
{
"proposal_id": proposal_id,
"decision_status": decision_status,
"tool_name": tool_name,
"preview": preview,
"payload": payload,
"original_tool_call_id": decision_data.get("original_tool_call_id"),
"message_id": decision_data.get("message_id"),
}
)
return result
def _get_cached_state(self, conversation: Conversation) -> ConversationStateResult:
if not hasattr(self, "_state_cache"):
self._state_cache: dict[str, ConversationStateResult] = {}
cache_key = str(conversation.id)
if cache_key not in self._state_cache:
self._state_cache[cache_key] = async_to_sync(self._aget_state)(conversation)
return self._state_cache[cache_key]
async def _aget_state(self, conversation: Conversation) -> ConversationStateResult:
"""Async implementation of state fetching with validation error detection.
Returns:
A ConversationStateResult; its interrupt_payloads maps proposal_id to the
interrupt value (including payload).
"""
return await aget_conversation_state(conversation, self.context["team"], self.context["user"])