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.

15.0 KB
Raw Blame
import type { BuiltLogic } from 'kea'
import posthog from 'posthog-js'

import { FEATURE_FLAGS } from 'lib/constants'
import { dayjs } from 'lib/dayjs'
import { humanFriendlyDuration } from 'lib/utils/durations'

import { isHogQLQuery, isInsightQueryNode } from '~/queries/schema/node-guards'
import { VisualizationBlock } from '~/queries/schema/schema-assistant-artifacts'
import {
    AgentMode,
    AnyAssistantGeneratedQuery,
    ArtifactContent,
    ArtifactContentType,
    ArtifactMessage,
    AssistantMessage,
    AssistantMessageType,
    AssistantToolCallMessage,
    AssistantUpdateEvent,
    FailureMessage,
    HumanMessage,
    MultiVisualizationMessage,
    NotebookArtifactContent,
    RootAssistantMessage,
    SubagentUpdateEvent,
    VisualizationArtifactContent,
    VisualizationItem,
} from '~/queries/schema/schema-assistant-messages'
import {
    DashboardFilter,
    DataVisualizationNode,
    HogQLVariable,
    InsightVizNode,
    NodeKind,
    QuerySchema,
    QuerySchemaRoot,
} from '~/queries/schema/schema-general'
import { ActionType, EventDefinition, InsightModel } from '~/types'

import { Scene } from '../sceneTypes'
import { MODE_DEFINITIONS } from './max-constants'
import { EnhancedToolCall } from './max-constants'
import { SuggestionGroup } from './maxLogic'
import {
    EvaluationRuntime,
    MaxActionContext,
    MaxContextItem,
    MaxContextType,
    MaxContextDashboard,
    MaxDashboardContext,
    MaxErrorTrackingIssueContext,
    MaxEvaluationContext,
    MaxEventContext,
    MaxInsightContext,
    MaxNotebookContext,
    MaxUIContext,
} from './maxTypes'

export function isMultiVisualizationMessage(
    message: RootAssistantMessage | undefined | null
): message is MultiVisualizationMessage {
    return message?.type === AssistantMessageType.MultiVisualization
}

export function isArtifactMessage(message: RootAssistantMessage | undefined | null): message is ArtifactMessage {
    return message?.type === AssistantMessageType.Artifact
}

export function isVisualizationArtifactContent(content: ArtifactContent): content is VisualizationArtifactContent {
    return content.content_type === ArtifactContentType.Visualization
}

export function isNotebookArtifactContent(content: ArtifactContent): content is NotebookArtifactContent {
    return content.content_type === ArtifactContentType.Notebook
}

export function isHumanMessage(message: RootAssistantMessage | undefined | null): message is HumanMessage {
    return message?.type === AssistantMessageType.Human
}

export function isAssistantMessage(message: RootAssistantMessage | undefined | null): message is AssistantMessage {
    return message?.type === AssistantMessageType.Assistant
}

export function isAssistantToolCallMessage(
    message: RootAssistantMessage | undefined | null
): message is AssistantToolCallMessage & Required<Pick<AssistantToolCallMessage, 'ui_payload'>> {
    return message?.type === AssistantMessageType.ToolCall && message.ui_payload !== undefined
}

export function isSubagentUpdateEvent(
    message: AssistantUpdateEvent | SubagentUpdateEvent | undefined | null
): message is SubagentUpdateEvent {
    return message?.content instanceof Object && 'type' in message.content && message.content.type === 'tool_call'
}

export function isFailureMessage(message: RootAssistantMessage | undefined | null): message is FailureMessage {
    return message?.type === AssistantMessageType.Failure
}

export function isMultiQuestionFormMessage(
    message: RootAssistantMessage | undefined | null
): message is AssistantMessage & { tool_calls: EnhancedToolCall[] } {
    return (
        isAssistantMessage(message) &&
        !!message.tool_calls &&
        message.tool_calls.some((toolCall) => toolCall.name === 'create_form')
    )
}

export function threadEndsWithMultiQuestionForm(messages: RootAssistantMessage[]): boolean {
    if (messages.length < 1) {
        return false
    }
    const lastMessage = messages[messages.length - 1]

    // The form is waiting for user input when the last message is an AssistantMessage with a create_form tool call.
    // The create_form tool raises NodeInterrupt(None) which doesn't produce any message, so the thread
    // ends with the AssistantMessage containing the tool call.
    if (isMultiQuestionFormMessage(lastMessage)) {
        return true
    }

    return false
}

export interface PendingClientToolCall {
    toolName: string
    toolCallId: string
    args: Record<string, any>
}

// A client tool call is pending when the current turn contains it with no result message.
// The whole turn is scanned, not just the last message: a sibling server-side tool's result
// may land after the assistant message carrying the client call.
export function findPendingClientToolCall(
    messages: RootAssistantMessage[],
    clientToolNames: Set<string>
): PendingClientToolCall | null {
    const lastHumanIndex = messages.findLastIndex(isHumanMessage)
    const currentTurn = messages.slice(lastHumanIndex + 1)

    const completedToolCallIds = new Set<string>()
    for (const message of messages) {
        if (message.type === AssistantMessageType.ToolCall && 'tool_call_id' in message) {
            completedToolCallIds.add((message as { tool_call_id: string }).tool_call_id)
        }
    }
    for (const message of currentTurn) {
        if (!isAssistantMessage(message) || !message.tool_calls?.length) {
            continue
        }
        for (const toolCall of message.tool_calls) {
            if (clientToolNames.has(toolCall.name) && !completedToolCallIds.has(toolCall.id)) {
                return { toolName: toolCall.name, toolCallId: toolCall.id, args: toolCall.args ?? {} }
            }
        }
    }
    return null
}

export function castAssistantQuery(query: AnyAssistantGeneratedQuery | QuerySchemaRoot | null): QuerySchemaRoot | null {
    if (query) {
        return query as QuerySchemaRoot
    }
    return null
}

export function formatConversationDate(updatedAt: string | null): string {
    if (!updatedAt) {
        return 'Some time ago'
    }

    const diff = dayjs().diff(dayjs(updatedAt), 'seconds')
    if (diff < 60) {
        return 'Just now'
    }
    return humanFriendlyDuration(diff, { maxUnits: 1 })
}

export function getSlackThreadUrl(slackThreadKey: string, slackWorkspaceDomain?: string | null): string {
    const [_, channel, threadTs] = slackThreadKey.split(':')
    // threadTs is like "1765374935.148729", URL needs "p1765374935148729"
    const urlTs = `p${threadTs.replace('.', '')}`
    const domain = slackWorkspaceDomain || 'slack'
    return `https://${domain}.slack.com/archives/${channel}/${urlTs}`
}

function stripQueryResponses<Value>(value: Value): Value {
    if (value === null || typeof value !== 'object') {
        return value
    }
    if (Array.isArray(value)) {
        return value.map(stripQueryResponses) as Value
    }

    const isQueryNode = 'kind' in value && Object.values(NodeKind).includes(value.kind as NodeKind)
    return Object.fromEntries(
        Object.entries(value)
            .filter(([key]) => !(isQueryNode && key === 'response'))
            .map(([key, child]) => [key, stripQueryResponses(child)])
    ) as Value
}

// Utility functions for transforming data to max context
export const insightToMaxContext = (
    insight: Partial<InsightModel>,
    filtersOverride?: DashboardFilter,
    variablesOverride?: Record<string, HogQLVariable>
): MaxInsightContext => {
    // Some insights (especially revenue analytics insights) don't have an inner source so we fallback to the outer query
    const source = (insight.query as any)?.source ?? insight.query

    return {
        type: MaxContextType.INSIGHT,
        id: insight.short_id!,
        name: insight.name || insight.derived_name,
        description: insight.description,
        query: stripQueryResponses(source),
        filtersOverride,
        variablesOverride,
    }
}

export const dashboardToMaxContext = (dashboard: MaxContextDashboard): MaxDashboardContext => {
    return {
        type: MaxContextType.DASHBOARD,
        id: dashboard.id,
        name: dashboard.name,
        description: dashboard.description,
        insights: (dashboard.tiles ?? [])
            .filter((tile) => tile.insight)
            .map((tile) => insightToMaxContext(tile.insight!)),
        filters: dashboard.filters,
    }
}

export const eventToMaxContextPayload = (event: EventDefinition): MaxEventContext => {
    return {
        type: MaxContextType.EVENT,
        id: event.id,
        name: event.name,
        description: event.description,
    }
}

export const actionToMaxContextPayload = (action: ActionType): MaxActionContext => {
    return {
        type: MaxContextType.ACTION,
        id: action.id,
        name: action.name || `Action ${action.id}`,
        description: action.description || '',
    }
}

export const errorTrackingIssueToMaxContextPayload = (issue: {
    id: string
    name?: string | null
}): MaxErrorTrackingIssueContext => {
    return {
        type: MaxContextType.ERROR_TRACKING_ISSUE,
        id: issue.id,
        name: issue.name,
    }
}

export const notebookToMaxContextPayload = (notebook: {
    short_id: string
    title?: string | null
}): MaxNotebookContext => ({
    type: MaxContextType.NOTEBOOK,
    id: notebook.short_id,
    name: notebook.title,
})

export const evaluationToMaxContextPayload = (evaluation: {
    id: string
    name?: string | null
    description?: string | null
    evaluation_type: EvaluationRuntime
    hog_source?: string | null
}): MaxEvaluationContext => ({
    type: MaxContextType.EVALUATION,
    id: evaluation.id,
    name: evaluation.name,
    description: evaluation.description,
    evaluation_type: evaluation.evaluation_type,
    hog_source: evaluation.hog_source,
})

/**
 * Generic context that can be passed when opening PostHog AI.
 */
export interface MaxOpenContext {
    /** Error tracking issue context */
    errorTrackingIssue?: {
        id: string
        name?: string | null
    }
    /** Evaluation context */
    evaluation?: {
        id: string
        name?: string | null
        description?: string | null
        evaluation_type: EvaluationRuntime
        hog_source?: string | null
    }
}

/**
 * Converts MaxOpenContext to MaxUIContext
 */
export function convertToMaxUIContext(openContext: MaxOpenContext): Partial<MaxUIContext> {
    const uiContext: Partial<MaxUIContext> = {}

    if (openContext.errorTrackingIssue) {
        uiContext.error_tracking_issues = [errorTrackingIssueToMaxContextPayload(openContext.errorTrackingIssue)]
    }

    if (openContext.evaluation) {
        uiContext.evaluations = [evaluationToMaxContextPayload(openContext.evaluation)]
    }

    return uiContext
}

export const createSuggestionGroup = (label: string, icon: JSX.Element, suggestions: string[]): SuggestionGroup => {
    return {
        label,
        icon,
        suggestions: suggestions.map((content) => ({ content })),
    }
}

export type FeedbackRating = 'bad' | 'okay' | 'good' | 'dismissed' | 'implicit_dismiss'
export type FeedbackTriggerType = 'message_interval' | 'random_sample' | 'manual' | 'retry' | 'cancel'

export function captureFeedback(
    conversationId: string,
    traceId: string | null,
    rating: FeedbackRating,
    triggerType: FeedbackTriggerType,
    feedbackText?: string
): void {
    posthog.capture('$ai_metric', {
        $ai_metric_name: 'feedback',
        $ai_metric_value: rating,
        $ai_session_id: conversationId,
        $ai_trace_id: traceId,
        feedback_trigger_type: triggerType,
    })

    if (feedbackText) {
        posthog.capture('$ai_feedback', {
            $ai_feedback_text: feedbackText,
            $ai_session_id: conversationId,
            $ai_trace_id: traceId,
            ai_product: 'posthog_ai',
        })
    }
}

/** Maps a scene ID to the agent mode that should be activated for that scene */
export function getAgentModeForScene(
    sceneId: Scene | null,
    featureFlags: Record<string, boolean | string>
): AgentMode | null {
    if (!sceneId) {
        return null
    }
    for (const [mode, def] of Object.entries(MODE_DEFINITIONS)) {
        if (def.scenes?.has(sceneId)) {
            if (def.flag && !featureFlags[FEATURE_FLAGS[def.flag]]) {
                return null
            }
            return mode as AgentMode
        }
    }
    return null
}

export const visualizationTypeToQuery = (
    visualization: VisualizationItem | VisualizationArtifactContent | VisualizationBlock
): QuerySchema | null => {
    if (!visualization) {
        return null
    }
    const source = castAssistantQuery('answer' in visualization ? visualization.answer : visualization.query)
    if (isHogQLQuery(source)) {
        return { kind: NodeKind.DataVisualizationNode, source: source } satisfies DataVisualizationNode
    }
    if (isInsightQueryNode(source)) {
        return { kind: NodeKind.InsightVizNode, source, showHeader: true } satisfies InsightVizNode
    }
    return source
}

/**
 * Whether it's safe to read auto-context from the active scene logic. `sceneLogic`'s
 * `activeSceneLogic` is built but may already be unmounted mid scene-transition (e.g. navigating
 * away from a dashboard); reading its selectors/values then throws `[KEA] Can not find path`
 * because the reducer path is gone from the store. Check this at read time — mounted state changes
 * without a selector-input change, so it can't be memoized upstream.
 */
export function activeSceneLogicHasMaxContext(
    activeSceneLogic: BuiltLogic | null | undefined
): activeSceneLogic is BuiltLogic {
    return !!activeSceneLogic?.isMounted() && 'maxContext' in activeSceneLogic.selectors
}

const UI_CONTEXT_FIELD_TYPES = {
    dashboards: MaxContextType.DASHBOARD,
    insights: MaxContextType.INSIGHT,
    events: MaxContextType.EVENT,
    actions: MaxContextType.ACTION,
    error_tracking_issues: MaxContextType.ERROR_TRACKING_ISSUE,
    evaluations: MaxContextType.EVALUATION,
    notebooks: MaxContextType.NOTEBOOK,
} as const satisfies Partial<Record<keyof MaxUIContext, MaxContextType>>

export type ContextSource = 'none' | 'page' | 'added' | 'mixed'

/**
 * Splits the context sent with a message into items the open page attached on its own and items
 * the user added (through the picker or an "ask AI" entry point), for turn telemetry.
 */
export function getContextSourceProperties(
    uiContext: MaxUIContext | null | undefined,
    sceneContext: MaxContextItem[]
): { context_source: ContextSource; page_context_count: number; added_context_count: number } {
    const sceneKeys = new Set(sceneContext.map((item) => `${item.type}:${item.id}`))
    let pageCount = 0
    let addedCount = 0
    for (const [field, type] of Object.entries(UI_CONTEXT_FIELD_TYPES)) {
        for (const item of uiContext?.[field as keyof typeof UI_CONTEXT_FIELD_TYPES] ?? []) {
            if (sceneKeys.has(`${type}:${item.id}`)) {
                pageCount++
            } else {
                addedCount++
            }
        }
    }
    const contextSource: ContextSource =
        pageCount > 0 && addedCount > 0 ? 'mixed' : pageCount > 0 ? 'page' : addedCount > 0 ? 'added' : 'none'
    return { context_source: contextSource, page_context_count: pageCount, added_context_count: addedCount }
}