: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 { useActions, useValues } from 'kea'
import { router } from 'kea-router'
import { useEffect, useMemo, useRef, useState } from 'react'
import { FEATURE_FLAGS } from 'lib/constants'
import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
import { uuid } from 'lib/utils/dom'
import { removeProjectIdIfPresent } from 'lib/utils/kea-router'
import { retryImport } from 'lib/utils/retryImport'
import { reloadAfterChunkLoadError } from 'lib/utils/stableChunks'
import { sceneLogic } from 'scenes/sceneLogic'
import { sceneConfigurations } from 'scenes/scenes'
import { MAX_SIDE_PANEL_ID } from '~/layout/ai/aiPanelIds'
import { aiShellLogic } from '~/layout/ai/aiShellLogic'
import { attachedContextItemKey } from '~/layout/ai/attachedContext'
import type { AttachedContextItem } from '~/layout/ai/attachedContext'
import { attachedContextLogic } from '~/layout/ai/attachedContextLogic'
import { runnerPanelLogic } from '~/layout/ai/runnerPanelLogic'
import { sidePanelLogic } from '~/layout/navigation-3000/sidepanel/sidePanelLogic'
import { SidePanelTab } from '~/types'
import type { ToolDefinition, ToolRegistration } from './max-constants'
export interface UseMaxToolOptions extends Omit<ToolRegistration, 'name' | 'description'> {
/** Whether MaxTool functionality is active. When false, tool is not registered. */
active?: boolean
/** Initial prompt to pass to Max when opened */
initialMaxPrompt?: string
/** Callback when Max panel opens */
onMaxOpen?: () => void
/** Optional: Describes what kind of context information is being provided */
contextDescription?: ToolRegistration['contextDescription']
}
export interface UseMaxToolReturn {
/** Tool definition - null if the tool is inactive (i.e. `active` is false or Max is not available), or while the tool table loads */
definition: ToolDefinition | null
/** Whether the Max side panel is currently open */
isMaxOpen: boolean
/** Function to open Max with the optional initialMaxPrompt and suggestions - null if the tool is inactive.
* It resolves once the panel is open: the first call waits for the Max chunk. */
openMax: (() => Promise<void>) | null
}
// The chat logics stay out of the shell chunk. The shell loads them on the first open.
const loadMaxToolOpener = (): Promise<typeof import('./maxToolOpener')> => retryImport(() => import('./maxToolOpener'))
// The tool table stays out of the shell chunk, and loads once a page turns a tool on.
type ToolDefinitionsModule = typeof import('./max-constants')
let loadedToolDefinitions: ToolDefinitionsModule | null = null
async function loadToolDefinitions(): Promise<ToolDefinitionsModule> {
loadedToolDefinitions ??= await retryImport(() => import('./max-constants'))
return loadedToolDefinitions
}
function useToolDefinitions(active: boolean): ToolDefinitionsModule | null {
const [toolDefinitions, setToolDefinitions] = useState(loadedToolDefinitions)
useEffect(() => {
if (!active || toolDefinitions) {
return
}
let cancelled = false
loadToolDefinitions().then(
(module) => {
if (!cancelled) {
setToolDefinitions(module)
}
},
// A failed load only hides the tool name. A click on openMax tells the person to reload.
() => {}
)
return (): void => {
cancelled = true
}
}, [active, toolDefinitions])
return toolDefinitions
}
const MAX_TOOL_CONTEXT_LENGTH = 4096
const TOOL_PAGE_CONTEXT_PROVIDER_ID = 'max-tool-page'
let toolPageContextOwner: string | null = null
function toolPageContextItems(
identifier: string,
context: Record<string, unknown> | undefined,
dismissGroup: string
): AttachedContextItem[] {
const path = removeProjectIdIfPresent(router.values.location.pathname)
const sceneId = sceneLogic.findMounted()?.values.activeSceneId
const sceneName = sceneId ? sceneConfigurations[sceneId]?.name : undefined
const items: AttachedContextItem[] = [{ type: 'page', key: path, label: sceneName || path, dismissGroup }]
const value = context && Object.keys(context).length > 0 ? JSON.stringify(context) : null
if (value && value.length <= MAX_TOOL_CONTEXT_LENGTH) {
items.push({ type: 'tool_context', label: identifier, value, hidden: true, dismissGroup })
}
return items
}
/** Hook for registering a MaxTool and handling Max interactions programmatically, without the full MaxTool wrapper. */
export function useMaxTool({
identifier,
context,
contextDescription,
introOverride,
callback,
clientExecution,
suggestions,
active = true,
initialMaxPrompt,
onMaxOpen,
}: UseMaxToolOptions): UseMaxToolReturn {
const { registerTool, deregisterTool } = useActions(aiShellLogic)
const { effectivePhaiView } = useValues(aiShellLogic)
const { registerContext, deregisterContext, undismissContext } = useActions(attachedContextLogic)
const { openSidePanel } = useActions(sidePanelLogic)
const { sidePanelOpen, selectedTab } = useValues(sidePanelLogic)
const { featureFlags } = useValues(featureFlagLogic)
const {
location: { pathname },
} = useValues(router)
const { activeCreation } = useValues(runnerPanelLogic({ panelId: MAX_SIDE_PANEL_ID }))
const openChat = activeCreation ? (activeCreation.taskId ? 'task' : 'draft') : null
const definition = useToolDefinitions(active)?.getToolDefinition(identifier) ?? null
const isMaxOpen = sidePanelOpen && selectedTab === SidePanelTab.Max
const activeIdentifierRef = useRef<string | null>(null)
const hookIdRef = useRef<string>(uuid())
const unmountedRef = useRef(false)
// openMax reads these after the chunk loads, so a change made meanwhile decides what reaches the chat.
const latestRef = useRef({ context, active })
latestRef.current = { context, active }
const contextKey = useMemo(() => JSON.stringify(context), [context])
// Register before the tool table loads, so a message sent at once still carries the tool context.
useEffect(() => {
if (!active) {
if (activeIdentifierRef.current) {
deregisterTool(activeIdentifierRef.current)
activeIdentifierRef.current = null
}
return
}
if (activeIdentifierRef.current && activeIdentifierRef.current !== identifier) {
deregisterTool(activeIdentifierRef.current)
}
activeIdentifierRef.current = identifier
registerTool({
identifier,
name: definition?.name,
description: definition?.description,
context,
contextDescription,
introOverride,
suggestions,
callback,
clientExecution,
})
// oxlint-disable-next-line react-hooks/exhaustive-deps -- context is tracked via contextKey (serialized) so identity churn doesn't re-register the tool
}, [
active,
identifier,
definition,
contextKey,
contextDescription,
introOverride,
suggestions,
callback,
clientExecution,
registerTool,
deregisterTool,
])
useEffect(() => {
if (toolPageContextOwner !== hookIdRef.current) {
return
}
if (!active || openChat === 'task') {
toolPageContextOwner = null
deregisterContext(TOOL_PAGE_CONTEXT_PROVIDER_ID)
return
}
if (openChat === 'draft') {
deregisterContext(TOOL_PAGE_CONTEXT_PROVIDER_ID)
return
}
registerContext(
TOOL_PAGE_CONTEXT_PROVIDER_ID,
toolPageContextItems(identifier, context, TOOL_PAGE_CONTEXT_PROVIDER_ID)
)
// oxlint-disable-next-line react-hooks/exhaustive-deps -- context is tracked via contextKey (serialized)
}, [active, identifier, contextKey, pathname, openChat, registerContext, deregisterContext])
useEffect(() => {
const hookId = hookIdRef.current
unmountedRef.current = false
return (): void => {
unmountedRef.current = true
if (activeIdentifierRef.current) {
deregisterTool(activeIdentifierRef.current)
activeIdentifierRef.current = null
}
if (toolPageContextOwner === hookId) {
toolPageContextOwner = null
deregisterContext(TOOL_PAGE_CONTEXT_PROVIDER_ID)
}
}
}, [deregisterTool, deregisterContext])
return {
definition: active ? definition : null,
isMaxOpen,
openMax: !active
? null
: async (): Promise<void> => {
let opener: Awaited<ReturnType<typeof loadMaxToolOpener>>
let toolDefinitions: ToolDefinitionsModule
try {
;[opener, toolDefinitions] = await Promise.all([loadMaxToolOpener(), loadToolDefinitions()])
} catch (error) {
// Click handlers drop a rejected promise, and no error boundary sees it.
lemonToast.error("Couldn't open PostHog AI. Reload the page to try again.", {
button: { label: 'Reload', action: () => reloadAfterChunkLoadError(error) },
})
return
}
const { startToolChat, showToolSuggestions } = opener
startToolChat({ todayRailNav: !!featureFlags[FEATURE_FLAGS.TODAY_RAIL_NAV], effectivePhaiView })
// The page may have closed, or the tool turned off, while the chunk loaded. Its context would then outlive the hook.
if (effectivePhaiView === 'new' && !unmountedRef.current && latestRef.current.active) {
toolPageContextOwner = hookIdRef.current
const items = toolPageContextItems(
identifier,
latestRef.current.context,
TOOL_PAGE_CONTEXT_PROVIDER_ID
)
undismissContext(attachedContextItemKey(items[0]), TOOL_PAGE_CONTEXT_PROVIDER_ID)
registerContext(TOOL_PAGE_CONTEXT_PROVIDER_ID, items)
}
// Show the suggestions from this specific tool
const toolDefinition = toolDefinitions.getToolDefinition(identifier)
if (toolDefinition && suggestions && suggestions.length > 0) {
showToolSuggestions(toolDefinition.name, suggestions)
}
openSidePanel(SidePanelTab.Max, initialMaxPrompt)
onMaxOpen?.()
},
}
}