Skip to content

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

12.1 KB
Raw Blame
"""Open a new user's first agent session."""

from uuid import UUID, uuid4

from django.conf import settings
from django.db import IntegrityError, transaction

import structlog
import posthoganalytics

from posthog.constants import AvailableFeature
from posthog.event_usage import groups
from posthog.helpers.email_utils import email_domain
from posthog.models.team.team import Team
from posthog.models.user import User
from posthog.temporal.oauth import MCP_READ_SCOPES

from products.signals.backend.facade.api import enable_onboarding_signal_sources, waiting_reports
from products.tasks.backend.facade.api import (
    create_and_run_task,
    desktop_users_in_team,
    ensure_personal_channel_id,
    find_general_channel_id,
    organization_has_context,
)
from products.tasks.backend.facade.domain_research import normalize_target, research_domain
from products.tasks.backend.facade.onboarding_brief import (
    OnboardingFacts,
    build_followup,
    build_opening_brief,
    prose_list,
)
from products.tasks.backend.facade.onboarding_canvas import TeachingCanvas, ensure_teaching_canvas
from products.tasks.backend.facade.onboarding_prompt import (
    BUNDLED_ONBOARDING_PROMPT,
    load_onboarding_prompt,
    missing_onboarding_prompt_placeholders,
    render_onboarding_prompt,
)
from products.tasks.backend.facade.profiles import TaskRunOptions
from products.tasks.backend.logic.services.model_catalogue import filter_unsupported_effort, runtime_adapter_for
from products.tasks.backend.models import Task, TaskClientProvenance
from products.tasks.backend.task_profiles import USER
from products.tasks.backend.task_sources import idempotency_key_q

from ee.billing.salesforce_enrichment.constants import PERSONAL_EMAIL_DOMAINS

logger = structlog.get_logger(__name__)

ONBOARDING_SESSION_TITLE = "Getting set up"
ONBOARDING_SESSION_PAID_MODEL = "claude-opus-4-8"
ONBOARDING_SESSION_FREE_MODEL = "zai-org/glm-5.3-flash"
ONBOARDING_SESSION_EFFORT = "medium"
ONBOARDING_SESSION_SCOPES = [*MCP_READ_SCOPES, "task:write", "inbox:write"]

SPACES_FLAGS = ("code-spaces-layout", "project-bluebird")
ONBOARDING_TEST_TOOLS_FLAG = "posthog-desktop-onboarding-test-tools"

ONBOARDING_ORIGIN_KEY_PREFIX = "desktop_onboarding_session"


def _origin_key(user_id: int) -> str:
    return f"{ONBOARDING_ORIGIN_KEY_PREFIX}:{user_id}"


def _started_session_id(team_id: int, user_id: int) -> UUID | None:
    return (
        Task.objects.filter(
            idempotency_key_q(_origin_key(user_id)),
            team_id=team_id,
            created_by_id=user_id,
            origin_product=Task.OriginProduct.USER_CREATED,
        )
        .values_list("id", flat=True)
        .first()
    )


def company_domain_from(email: str) -> str | None:
    domain = email_domain(email.strip().lower())
    if not domain or domain in PERSONAL_EMAIL_DOMAINS:
        return None
    return normalize_target(domain)


def onboarding_session_model(team: Team) -> str:
    if team.organization.is_feature_available(AvailableFeature.POSTHOG_CODE_USAGE):
        return ONBOARDING_SESSION_PAID_MODEL
    return ONBOARDING_SESSION_FREE_MODEL


def gather_onboarding_facts(team: Team, user: User) -> tuple[OnboardingFacts, str]:
    sources = enable_onboarding_signal_sources(team.id, user.id)
    waiting = waiting_reports(team.id)

    if organization_has_context(team.organization_id):
        return (
            OnboardingFacts(
                org_has_context=True,
                has_events=bool(team.ingested_event),
                signal_reports_waiting=waiting.count,
                reports_to_offer=waiting.offerable,
                other_members=prose_list(desktop_users_in_team(team, user.id)),
                sources_enabled=sources.labels,
                sources_watching=sources.watches,
                sources_newly_enabled=sources.newly_enabled,
            ),
            "",
        )

    domain = company_domain_from(user.email)
    research = research_domain(domain) if domain else None
    facts = OnboardingFacts(
        org_has_context=False,
        research=research,
        has_events=bool(team.ingested_event),
        signal_reports_waiting=waiting.count,
        reports_to_offer=waiting.offerable,
        sources_enabled=sources.labels,
        sources_watching=sources.watches,
        sources_newly_enabled=sources.newly_enabled,
    )
    homepage = research.markdown or "" if research and research.outcome == "scraped" else ""
    return facts, homepage


def _session_enabled(team: Team, user: User) -> bool:
    if settings.DEBUG:
        return True

    distinct_id = user.distinct_id
    if not distinct_id:
        return False
    organization_id = str(team.organization_id)
    try:
        return all(
            bool(
                posthoganalytics.feature_enabled(
                    flag,
                    distinct_id=distinct_id,
                    groups={"organization": organization_id},
                    group_properties={"organization": {"id": organization_id}},
                    only_evaluate_locally=False,
                    send_feature_flag_events=False,
                )
            )
            for flag in SPACES_FLAGS
        )
    except Exception:
        logger.warning("onboarding_session_flag_check_failed", team_id=team.id)
        return False


def onboarding_test_tools_enabled(team: Team, user: User) -> bool:
    if settings.DEBUG:
        return True

    distinct_id = user.distinct_id
    if not distinct_id:
        return False
    organization_id = str(team.organization_id)
    try:
        return bool(
            posthoganalytics.feature_enabled(
                ONBOARDING_TEST_TOOLS_FLAG,
                distinct_id=distinct_id,
                groups={"organization": organization_id},
                group_properties={"organization": {"id": organization_id}},
                only_evaluate_locally=False,
                send_feature_flag_events=False,
            )
        )
    except Exception:
        logger.warning("onboarding_test_tools_flag_check_failed", team_id=team.id)
        return False


def _teaching_canvas(team_id: int, channel_id: UUID, user: User, *, refresh: bool) -> TeachingCanvas | None:
    """Best-effort: a session without the tour beats no session."""
    try:
        return ensure_teaching_canvas(team_id, channel_id, user, refresh=refresh)
    except Exception:
        logger.warning("onboarding_teaching_canvas_failed", team_id=team_id, exc_info=True)
        return None


def start_onboarding_session(
    team: Team,
    user: User,
    *,
    facts_override: OnboardingFacts | None = None,
    homepage_override: str = "",
    force: bool = False,
    channel_id: UUID | None = None,
    model: str | None = None,
) -> UUID | None:
    """Create the session a new user lands in. ``None`` when no session was started."""
    if not force and not _session_enabled(team, user):
        logger.info("onboarding_session_skipped", team_id=team.id, reason="flag_disabled")
        return None

    if channel_id is None:
        channel_id = find_general_channel_id(team.id)
    if channel_id is None:
        logger.info("onboarding_session_skipped", team_id=team.id, reason="no_general_channel")
        return None

    started = None if force else _started_session_id(team.id, user.id)
    if started is not None:
        logger.info("onboarding_session_skipped", team_id=team.id, reason="already_started")
        return started

    origin_key = f"{ONBOARDING_ORIGIN_KEY_PREFIX}_test:{user.id}:{uuid4()}" if force else _origin_key(user.id)

    teaching = _teaching_canvas(team.id, channel_id, user, refresh=force)
    facts, homepage = (
        (facts_override, homepage_override) if facts_override is not None else gather_onboarding_facts(team, user)
    )
    prompt = load_onboarding_prompt()
    missing_placeholders = missing_onboarding_prompt_placeholders(prompt.prompt)
    prompt_template = prompt.prompt
    if missing_placeholders:
        logger.error(
            "onboarding_prompt_missing_placeholders",
            missing_placeholders=missing_placeholders,
            prompt_source=prompt.source,
            prompt_version=prompt.version,
            team_id=team.id,
        )
        posthoganalytics.capture(
            distinct_id=str(user.distinct_id),
            event="Onboarding prompt fallback used",
            properties={
                "reason": "missing_placeholders",
                "missing_placeholders": missing_placeholders,
                "prompt_source": prompt.source,
                "prompt_version": prompt.version,
            },
            groups=groups(team.organization, team),
        )
        prompt_template = BUNDLED_ONBOARDING_PROMPT
    description = render_onboarding_prompt(
        prompt_template,
        brief=build_opening_brief(facts),
        followup=build_followup(facts, teaching=teaching),
        homepage=homepage,
        channel_id=str(channel_id),
    )
    session_model = model or onboarding_session_model(team)
    session_runtime_adapter = runtime_adapter_for(session_model)

    try:
        with transaction.atomic():
            created = create_and_run_task(
                team=team,
                title=ONBOARDING_SESSION_TITLE,
                title_manually_set=True,
                description=description,
                profile=USER,
                user_id=user.id,
                channel_id=channel_id,
                origin_key=origin_key,
                client_provenance=TaskClientProvenance.POSTHOG_DESKTOP,
                options=TaskRunOptions(
                    adapter=session_runtime_adapter,
                    model=session_model,
                    reasoning_effort=filter_unsupported_effort(
                        session_runtime_adapter, session_model, ONBOARDING_SESSION_EFFORT
                    ),
                    mcp_scopes=ONBOARDING_SESSION_SCOPES,
                    permission_mode="auto",
                ),
                create_pr=False,
                mode="interactive",
            )
    except IntegrityError:
        started = _started_session_id(team.id, user.id)
        if started is None:
            raise
        logger.info("onboarding_session_skipped", team_id=team.id, reason="already_started")
        return started
    logger.info(
        "onboarding_session_started",
        team_id=team.id,
        prompt_source=prompt.source,
        prompt_version=prompt.version,
        research_outcome=facts.research.outcome if facts.research else None,
        sources_enabled=facts.sources_enabled,
        sources_newly_enabled=facts.sources_newly_enabled,
    )
    posthoganalytics.capture(
        distinct_id=str(user.distinct_id),
        event="Onboarding domain research completed",
        properties={
            "task_id": str(created.task_id),
            "outcome": facts.research.outcome if facts.research else "not_applicable",
        },
        groups=groups(team.organization, team),
    )
    return created.task_id


def start_onboarding_test_session(
    team: Team,
    user: User,
    *,
    company_domain: str,
    joining_existing_organization: bool,
    has_events: bool,
    signal_reports_waiting: int,
    other_members: list[str],
    sources_enabled: list[str],
    sources_watching: list[str],
    sources_newly_enabled: bool,
    model: str | None,
) -> UUID | None:
    """Runs in the requester's personal space, so repeated tests leave #general alone."""
    domain = normalize_target(company_domain) if company_domain else None
    research = research_domain(domain) if domain and not joining_existing_organization else None
    facts = OnboardingFacts(
        org_has_context=joining_existing_organization,
        research=research,
        has_events=has_events,
        signal_reports_waiting=signal_reports_waiting,
        other_members=prose_list(other_members),
        sources_enabled=tuple(sources_enabled),
        sources_watching=tuple(sources_watching),
        sources_newly_enabled=sources_newly_enabled,
    )
    homepage = research.markdown or "" if research and research.outcome == "scraped" else ""
    return start_onboarding_session(
        team,
        user,
        facts_override=facts,
        homepage_override=homepage,
        force=True,
        channel_id=ensure_personal_channel_id(team.id, user.id),
        model=model,
    )