: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 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 }
}