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.

64.2 KB
Raw Blame
import {
    IconAtSign,
    IconBook,
    IconBrain,
    IconCheckbox,
    IconCloud,
    IconCreditCard,
    IconDocument,
    IconGlobe,
    IconMemory,
    IconNotebook,
    IconNotification,
    IconPeople,
    IconPlug,
    IconSearch,
    IconShuffle,
} from '@posthog/icons'

import { FEATURE_FLAGS } from 'lib/constants'
import { IconQuestionAnswer, IconRobot } from 'lib/lemon-ui/icons'
import { isObject } from 'lib/utils/guards'
import { Scene } from 'scenes/sceneTypes'

import { iconForType } from '~/layout/panel-layout/ProjectTree/defaultTree'
import { insightsModel } from '~/models/insightsModel'
import {
    AgentMode,
    AssistantTool,
    AssistantToolCall,
    AssistantToolCallMessage,
    TaskExecutionStatus,
} from '~/queries/schema/schema-assistant-messages'
import { InsightShortId, RecordingUniversalFilters } from '~/types'

export interface EnhancedToolCall extends AssistantToolCall {
    status: TaskExecutionStatus
    isLastPlanningMessage?: boolean
    updates?: string[]
    /** The tool call result message, if available */
    result?: AssistantToolCallMessage
}

export interface DisplayFormatterContext {
    registeredToolMap: Record<string, ToolRegistration>
}

/**
 * Longest message the server accepts. Mirrors `MAX_MESSAGE_CONTENT_LENGTH` in ee/api/conversation.py;
 * keep the two in sync. Anything longer comes back as a 400 on the `content` field.
 */
export const MAX_MESSAGE_LENGTH = 40000

/** Shown when a message is over `MAX_MESSAGE_LENGTH`, both before sending and if the server rejects it. */
export const MESSAGE_TOO_LONG = `Your message is too long. Shorten it to ${MAX_MESSAGE_LENGTH.toLocaleString()} characters or fewer.`

/**
 * Counts the way the server's `CharField` does: it trims whitespace, then measures Unicode code
 * points (Python `len`), not UTF-16 units. Emoji are one code point each but two UTF-16 units, so
 * `String.length` would reject messages the server accepts.
 */
export function messageLength(content: string): number {
    return Array.from(content.trim()).length
}

/** Static tool definition for display purposes. */
export interface ToolDefinition<N extends string = string> {
    /** A user-friendly display name for the tool. Must be a verb phrase, like "Create surveys" or "Search docs" */
    name: N
    /**
     * The tool's description, which must be a sentence that's an extension of the name,
     * e.g. "Create surveys in seconds"
     */
    description?: `${N} ${string}`
    /** If the tool has multiple subtools, you can specify them here
     * These will populate the tool summary list, instead of the tool itself
     */
    subtools?: Record<
        string, // identifier, should match the "kind" key in the tool call
        ToolDefinition
    >
    icon: JSX.Element
    displayFormatter?: (
        toolCall: EnhancedToolCall,
        { registeredToolMap }: DisplayFormatterContext
    ) => string | [text: string, widgetDef: RecordingsWidgetDef | ReplayVisionScanWidgetDef | null]
    onResult?: (result: any) => void
    /**
     * If only available in a specific product, specify it here.
     * We're using Scene instead of ProductKey, because that's more flexible (specifically for SQL editor there
     * isn't ProductKey.SQL_EDITOR, only ProductKey.DATA_WAREHOUSE - much clearer for users to say Scene.SQLEditor here)
     */
    product?: Scene
    /** If the tool is only available if a feature flag is enabled, you can specify it here. */
    flag?: (typeof FEATURE_FLAGS)[keyof typeof FEATURE_FLAGS]
    /** If the tool is in beta, set this to true to display a beta badge */
    beta?: boolean
    /** If the tool is in alpha, set this to true to display an alpha badge */
    alpha?: boolean
    /** Agent modes this tool is available in (defined in backend presets) */
    modes?: AgentMode[]
    /**
     * Set for tools using ToolRegistration.clientExecution, so a pending call is resumed with
     * a refusal (instead of stranded) after the owning view deregistered the handler.
     */
    clientExecuted?: boolean
}

/** Active instance of a tool. */
export interface ToolRegistration extends Partial<Pick<ToolDefinition, 'name' | 'description'>> {
    /** A unique identifier for the tool */
    identifier: keyof typeof TOOL_DEFINITIONS
    /**
     * Optional specific @posthog/icons icon
     * @default <IconWrench />
     */
    /** Contextual data to be included for use by the LLM */
    context?: Record<string, any>
    /**
     * Optional: Describes what kind of context information is being provided
     * This metadata is shown to users in the context topbar to indicate what contextual values are available
     */
    contextDescription?: {
        /** The type or category of context (e.g., "Current insight", "Active filters") */
        text: string
        /** Icon to display for the context type */
        icon: JSX.Element
    }
    /**
     * Optional: If this tool is the main one of the page, you can override the default intro headline and description when it's mounted.
     *
     * Note that if more than one mounted tool has an intro override, only one will take effect.
     */
    introOverride?: {
        /** The default is something like "How can I help you build?" - stick true to this question form. */
        headline: string
        /** The default is "Ask me about your product and your users." */
        description: string
    }
    /** Optional: When in context, the tool can add items to the pool of suggested questions */
    suggestions?: string[]
    /** The callback function that will be executed with the LLM's tool call output */
    callback?: (toolOutput: any, conversationId: string) => void | Promise<void>
    /**
     * Optional: executes part of the tool client-side. Runs with the tool call's arguments when
     * the backend pauses via `MaxTool.request_client_execution()`; the returned result resumes
     * the conversation and becomes that call's return value. Keep results small (verdicts, ids):
     * they ride a Temporal resume payload capped at ~2MiB.
     */
    clientExecution?: (args: Record<string, any>) => Promise<Record<string, unknown>>
}

export interface RecordingsWidgetDef {
    widget: 'recordings'
    args: RecordingUniversalFilters
}

export interface ReplayVisionScanWidgetDef {
    widget: 'replay_vision_scan'
    args: { scanId: string; sessionIds: string[]; skipped: { sessionId: string; reason: string }[] }
}

/** Static mode definition for display purposes. */
export interface ModeDefinition {
    name: string
    description: string
    icon: JSX.Element
    /** Scenes that should trigger this agent mode */
    scenes?: Set<Scene>
    beta?: boolean
    alpha?: boolean
    /** Feature flag key that gates this mode. When set, the mode is only available if the flag is enabled. */
    flag?: keyof typeof FEATURE_FLAGS
}

/** Default tools available in all modes */
export const DEFAULT_TOOL_KEYS: (keyof typeof TOOL_DEFINITIONS)[] = [
    'read_taxonomy',
    'read_data',
    'list_data',
    'list_feature_flags',
    'search',
    'switch_mode',
    'list_llm_skills',
    'get_llm_skill',
    'get_llm_skill_file',
]

function skillStatusFormatter(
    toolCall: EnhancedToolCall,
    { completedLabel, pendingLabel, nameArgKey }: { completedLabel: string; pendingLabel: string; nameArgKey?: string }
): string {
    const rawName = nameArgKey ? toolCall.args?.[nameArgKey] : undefined
    const suffix = typeof rawName === 'string' && rawName ? ` "${rawName}"` : ''
    if (toolCall.status === 'completed') {
        return `${completedLabel}${suffix}`
    }
    return `${pendingLabel}${suffix}...`
}

/** Only these produce a row to wait for. Anything else is reported rather than polled for. */
const OUTCOMES_THAT_MINT_AN_OBSERVATION = ['started', 'already_running', 'already_scanned']

/**
 * The scan tool reports what it started, per session, and the results land later on the scanner it
 * minted. Sessions it skipped never get a row, so they are carried separately rather than left to
 * look like work still in progress.
 */
function replayVisionScanWidgetDef(toolCall: EnhancedToolCall): ReplayVisionScanWidgetDef | null {
    const payload = toolCall.result?.ui_payload?.scan_replay_vision_sessions
    const scanId = typeof payload?.scan_id === 'string' ? payload.scan_id : null
    if (!scanId || !Array.isArray(payload?.results)) {
        return null
    }
    const results = payload.results as { session_id?: unknown; scan_outcome?: unknown }[]
    const sessionIds: string[] = []
    const skipped: { sessionId: string; reason: string }[] = []
    for (const result of results) {
        if (typeof result?.session_id !== 'string' || typeof result?.scan_outcome !== 'string') {
            continue
        }
        if (OUTCOMES_THAT_MINT_AN_OBSERVATION.includes(result.scan_outcome)) {
            sessionIds.push(result.session_id)
        } else {
            skipped.push({ sessionId: result.session_id, reason: result.scan_outcome })
        }
    }
    if (!sessionIds.length && !skipped.length) {
        return null
    }
    return { widget: 'replay_vision_scan', args: { scanId, sessionIds, skipped } }
}

export const TOOL_DEFINITIONS: Record<AssistantTool, ToolDefinition> = {
    call_mcp_server: {
        name: 'Call an MCP server',
        description: 'Call an MCP server',
        icon: <IconPlug />,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Called an MCP server'
            }
            return 'Calling an MCP server...'
        },
    },
    todo_write: {
        name: 'Write a todo',
        description: 'Write a todo to remember a task',
        icon: <IconCheckbox />,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return `Update the to-do list`
            }
            return `Updating the to-do list...`
        },
    },
    task: {
        name: 'Run an agent to perform a task',
        description: 'Run an agent to perform a task',
        icon: <IconRobot />,
        displayFormatter: (toolCall) => {
            const title = toolCall.args.title
            if (toolCall.status === 'completed') {
                return `Task (${title})`
            }
            return title ? `Running a task (${title})...` : 'Running a task...'
        },
    },
    create_form: {
        name: 'Create a form',
        description: 'Create a form to collect information from the user',
        icon: <IconQuestionAnswer />,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created a form'
            }
            return 'Creating a form...'
        },
    },
    search: {
        name: 'Search PostHog data',
        description:
            'Search PostHog data for documentation, insights, dashboards, cohorts, actions, experiments, feature flags, notebooks, error tracking issues, surveys, and other.',
        icon: <IconSearch />,
        displayFormatter: function readDataDisplayFormatter(
            toolCall: EnhancedToolCall,
            context: DisplayFormatterContext
        ) {
            if (
                this.subtools &&
                'kind' in toolCall.args &&
                typeof toolCall.args.kind === 'string' &&
                toolCall.args.kind in this.subtools
            ) {
                const { displayFormatter } = this.subtools[toolCall.args.kind]
                if (displayFormatter) {
                    return displayFormatter(toolCall, context)
                }
            }

            if (toolCall.status === 'completed') {
                return 'Searched data'
            }

            return 'Searching data...'
        },
        subtools: {
            docs: {
                name: 'Search docs',
                description: 'Search docs for answers regarding PostHog',
                icon: <IconBook />,
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched docs'
                    }
                    return 'Searching docs...'
                },
            },
            insights: {
                name: 'Search existing insights',
                description: 'Search existing insights for answers',
                icon: iconForType('product_analytics'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched insights'
                    }
                    return 'Searching insights...'
                },
            },
            dashboards: {
                name: 'Search dashboards',
                description: 'Search dashboards for answers',
                icon: iconForType('product_analytics'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched dashboards'
                    }
                    return 'Searching dashboards...'
                },
            },
            cohorts: {
                name: 'Search cohorts',
                description: 'Search cohorts for answers',
                icon: iconForType('cohort'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched cohorts'
                    }
                    return 'Searching cohorts...'
                },
            },
            actions: {
                name: 'Search actions',
                description: 'Search actions for answers',
                icon: iconForType('action'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched actions'
                    }
                    return 'Searching actions...'
                },
            },
            experiments: {
                name: 'Search experiments',
                description: 'Search experiments for answers',
                icon: iconForType('experiment'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched experiments'
                    }
                    return 'Searching experiments...'
                },
            },
            feature_flags: {
                name: 'Search feature flags',
                description: 'Search feature flags for answers',
                icon: iconForType('feature_flag'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched feature flags'
                    }
                    return 'Searching feature flags...'
                },
            },
            notebooks: {
                name: 'Search notebooks',
                description: 'Search notebooks for answers',
                icon: iconForType('notebook'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched notebooks'
                    }
                    return 'Searching notebooks...'
                },
            },
            surveys: {
                name: 'Search surveys',
                description: 'Search surveys for answers',
                icon: iconForType('survey'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched surveys'
                    }
                    return 'Searching surveys...'
                },
            },
            error_tracking_issues: {
                name: 'Search error tracking issues',
                description: 'Search error tracking issues for answers',
                icon: iconForType('error_tracking'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched error tracking issues'
                    }
                    return 'Searching error tracking issues...'
                },
            },
            all: {
                name: 'Search all entities',
                description: 'Search all entities for answers',
                icon: <IconSearch />,
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Searched all entities'
                    }
                    return 'Searching all entities...'
                },
            },
        },
    },
    read_taxonomy: {
        name: 'Read data schema',
        description: 'Read data schema to retrieve events, properties, and sample property values',
        icon: iconForType('data_warehouse'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Read data schema'
            }
            return 'Reading data schema...'
        },
    },
    read_data: {
        name: 'Read data',
        description: 'Read data, such as your data warehouse schema and billed usage statistics',
        icon: iconForType('data_warehouse'),
        displayFormatter: function readDataDisplayFormatter(
            toolCall: EnhancedToolCall,
            context: DisplayFormatterContext
        ) {
            if (
                this.subtools &&
                isObject(toolCall.args?.query) &&
                toolCall.args.query &&
                'kind' in toolCall.args.query &&
                typeof toolCall.args.query.kind === 'string' &&
                toolCall.args.query.kind in this.subtools
            ) {
                const { displayFormatter } = this.subtools[toolCall.args.query.kind]
                if (displayFormatter) {
                    return displayFormatter(toolCall, context)
                }
            }

            if (toolCall.status === 'completed') {
                return 'Read data'
            }

            return 'Reading data...'
        },
        subtools: {
            billing_info: {
                name: 'Check your billing data',
                description: 'Check your billing data',
                icon: <IconCreditCard />,
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Read billing data'
                    }
                    return 'Reading billing data...'
                },
            },
            data_warehouse_schema: {
                name: 'Read data warehouse schema',
                description: 'Read data warehouse schema available in this project',
                icon: iconForType('data_warehouse'),
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Read data warehouse schema'
                    }
                    return 'Reading data warehouse schema...'
                },
            },
            data_warehouse_table: {
                name: 'Read data warehouse table schema',
                description: 'Read data warehouse table schema for a specific table',
                icon: iconForType('data_warehouse'),
                displayFormatter: (toolCall) => {
                    const tableName =
                        isObject(toolCall.args?.query) && 'table_name' in toolCall.args.query
                            ? toolCall.args.query.table_name
                            : null

                    if (toolCall.status === 'completed') {
                        return tableName ? `Read schema for \`${tableName}\`` : 'Read data warehouse table schema'
                    }
                    return tableName
                        ? `Reading schema for \`${tableName}\`...`
                        : 'Reading data warehouse table schema...'
                },
            },
            artifacts: {
                name: 'Read conversation artifacts',
                description: 'Read conversation artifacts created by the agent',
                icon: <IconDocument />,
                displayFormatter: (toolCall) => {
                    if (toolCall.status === 'completed') {
                        return 'Read conversation artifacts'
                    }
                    return 'Reading conversation artifacts...'
                },
            },
            insight: {
                name: 'Retrieve an insight',
                description: 'Retrieve an insight data',
                icon: iconForType('product_analytics'),
                displayFormatter: (toolCall) => {
                    function isExecuting(): boolean {
                        return !!(
                            isObject(toolCall.args?.query) &&
                            toolCall.args?.query &&
                            'execute' in toolCall.args?.query &&
                            toolCall.args?.query.execute
                        )
                    }

                    if (toolCall.status === 'completed') {
                        return isExecuting() ? 'Analyzed an insight' : 'Retrieved an insight'
                    }
                    return isExecuting() ? 'Analyzing an insight...' : 'Retrieving an insight...'
                },
            },
            dashboard: {
                name: 'Retrieve a dashboard',
                description: 'Retrieve a dashboard data',
                icon: iconForType('product_analytics'),
                displayFormatter: (toolCall) => {
                    function isExecuting(): boolean {
                        return !!(
                            isObject(toolCall.args?.query) &&
                            toolCall.args?.query &&
                            'execute' in toolCall.args?.query &&
                            toolCall.args?.query.execute
                        )
                    }

                    if (toolCall.status === 'completed') {
                        return isExecuting() ? 'Analyzed a dashboard' : 'Retrieved a dashboard'
                    }
                    return isExecuting() ? 'Analyzing a dashboard...' : 'Retrieving a dashboard...'
                },
            },
        },
    },
    list_data: {
        name: 'List data',
        description: 'List data with pagination to browse PostHog entities',
        icon: <IconSearch />,
        displayFormatter: (toolCall) => {
            const kind = typeof toolCall.args?.kind === 'string' ? toolCall.args.kind : null
            const offset = typeof toolCall.args?.offset === 'number' ? toolCall.args.offset : 0
            const entityLabel = (kind ? kind.replace(/_/g, ' ') : 'entities').toLowerCase()
            const pageInfo = offset > 0 ? ` (page ${Math.floor(offset / 100) + 1})` : ''

            if (toolCall.status === 'completed') {
                return `Listed ${entityLabel}${pageInfo}`
            }
            return `Listing ${entityLabel}${pageInfo}...`
        },
    },
    list_feature_flags: {
        name: 'List feature flags',
        description: 'List feature flags with their status, filterable by stale/enabled/disabled',
        icon: <IconSearch />,
        displayFormatter: (toolCall) => {
            const status = typeof toolCall.args?.status === 'string' ? toolCall.args.status : null
            const offset = typeof toolCall.args?.offset === 'number' ? toolCall.args.offset : 0
            const pageInfo = offset > 0 ? ` (page ${Math.floor(offset / 100) + 1})` : ''
            const label = status ? `${status} feature flags` : 'feature flags'
            return toolCall.status === 'completed' ? `Listed ${label}${pageInfo}` : `Listing ${label}${pageInfo}...`
        },
    },
    create_insight: {
        name: 'Create an insight or edit an existing one',
        description: "Create an insight or edit an existing one you're viewing",
        icon: iconForType('product_analytics'),
        product: Scene.Insight,
        modes: [AgentMode.ProductAnalytics],
        onResult: (result) => {
            if (result?.saved_insight?.short_id) {
                insightsModel.actions.insightSaved(result.saved_insight.short_id as InsightShortId)
            }
        },
        displayFormatter: (toolCall, { registeredToolMap }) => {
            if (toolCall.args?.insight_id) {
                return toolCall.status === 'completed' ? 'Updated insight' : 'Updating insight...'
            }
            const isEditing = registeredToolMap.create_insight
            if (isEditing) {
                return toolCall.status === 'completed'
                    ? 'Edited the insight you are viewing'
                    : 'Editing the insight you are viewing...'
            }
            return toolCall.status === 'completed' ? 'Created an insight' : 'Creating an insight...'
        },
    },
    search_session_recordings: {
        name: 'Search recordings',
        description: 'Search recordings quickly',
        product: Scene.Replay,
        icon: iconForType('session_replay'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Searched recordings'
            }
            return 'Searching recordings...'
        },
    },
    filter_session_recordings: {
        name: 'Filter recordings',
        description: 'Filter recordings to find the most relevant ones',
        product: Scene.Replay,
        icon: iconForType('session_replay'),
        displayFormatter: (toolCall) => {
            const widgetDef = toolCall.args?.recordings_filters
                ? ({
                      widget: 'recordings',
                      args: toolCall.args.recordings_filters as RecordingUniversalFilters,
                  } as const)
                : null
            if (toolCall.status === 'completed') {
                return ['Filtered recordings', widgetDef]
            }
            return ['Filtering recordings...', widgetDef]
        },
    },
    create_hog_function_filters: {
        name: 'Set up function filters',
        description: 'Set up function filters for quick pipeline configuration',
        product: Scene.Transformations,
        icon: iconForType('data_warehouse'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Set up function filters'
            }
            return 'Setting up function filters...'
        },
    },
    create_hog_transformation_function: {
        name: 'Write and tweak Hog code',
        description: 'Write and tweak Hog code of transformations',
        product: Scene.Transformations,
        icon: iconForType('data_warehouse'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Edited Hog code'
            }
            return 'Writing and tweaking Hog code...'
        },
    },
    create_hog_function_inputs: {
        name: 'Manage function variables',
        description: 'Manage function variables in Hog functions',
        product: Scene.Transformations,
        icon: iconForType('data_warehouse'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Managed function variables'
            }
            return 'Managing function variables...'
        },
    },
    filter_error_tracking_issues: {
        name: 'Filter issues',
        description: 'Filter issues to dig into errors',
        product: Scene.ErrorTracking,
        icon: iconForType('error_tracking'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Filtered issues'
            }
            return 'Filtering issues...'
        },
    },
    upsert_account: {
        name: 'Manage accounts',
        description: 'Manage accounts by creating them or updating roles, properties, and tags',
        product: Scene.CustomerAnalytics,
        icon: iconForType('cohort'),
        modes: [AgentMode.CustomerAnalytics],
        displayFormatter: (toolCall) => {
            const action = toolCall.args?.action
            const isUpdate = isObject(action) && 'action' in action && action.action === 'update'
            if (isUpdate) {
                return toolCall.status === 'completed' ? 'Updated account' : 'Updating account...'
            }
            return toolCall.status === 'completed' ? 'Created account' : 'Creating account...'
        },
    },
    upsert_account_notebook: {
        name: 'Manage account notes',
        description: 'Manage account notes — call recaps, summaries, or edits to an existing note',
        product: Scene.CustomerAnalytics,
        icon: iconForType('notebook'),
        modes: [AgentMode.CustomerAnalytics],
        displayFormatter: (toolCall) => {
            const action = toolCall.args?.action
            const isUpdate = isObject(action) && 'action' in action && action.action === 'update'
            if (isUpdate) {
                return toolCall.status === 'completed' ? 'Updated account note' : 'Updating account note...'
            }
            return toolCall.status === 'completed' ? 'Created account note' : 'Creating account note...'
        },
    },
    open_account: {
        name: 'Open account',
        description: 'Open account details and tabs',
        product: Scene.CustomerAnalytics,
        icon: <IconPeople />,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Opened account'
            }
            return 'Opening account...'
        },
    },
    search_error_tracking_issues: {
        name: 'Search issues',
        description: 'Search issues in error tracking',
        product: Scene.ErrorTracking,
        icon: iconForType('error_tracking'),
        modes: [AgentMode.ErrorTracking],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Found issues'
            }
            return 'Searching issues...'
        },
    },
    find_error_tracking_impactful_issue_event_list: {
        name: 'Find impactful issues',
        description: 'Find impactful issues affecting your conversion, activation, or any other events',
        product: Scene.ErrorTracking,
        flag: FEATURE_FLAGS.ERROR_TRACKING_ISSUE_CORRELATION,
        icon: iconForType('error_tracking'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Found impactful issues'
            }
            return 'Finding impactful issues...'
        },
    },
    experiment_results_summary: {
        name: 'Summarize experiment results',
        description: 'Summarize experiment results for a comprehensive rundown',
        product: Scene.Experiment,
        icon: iconForType('experiment'),
        modes: [AgentMode.Flags],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Summarized experiment results'
            }
            return 'Summarizing experiment results...'
        },
    },
    compare_replay_vision_variants: {
        name: 'Compare experiment variants',
        description: 'Compare experiment variants: what an experiment scanner found in each variant',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Compared experiment variants'
            }
            return 'Comparing experiment variants...'
        },
    },
    draft_replay_vision_scanner_prompt: {
        name: 'Write scanner prompts',
        description: 'Write scanner prompts for Replay Vision scanners',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Drafted scanner prompt'
            }
            return 'Drafting scanner prompt...'
        },
    },
    search_replay_vision_observations: {
        name: 'Search observations',
        description: "Search observations by the meaning of a Replay Vision scanner's model reasoning",
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Searched observations'
            }
            return 'Searching observations...'
        },
    },
    scan_replay_vision_sessions: {
        name: 'Scan recordings',
        description: 'Scan recordings with Replay Vision to answer a question about them',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status !== 'completed') {
                return 'Starting scans...'
            }
            return ['Scanned recordings', replayVisionScanWidgetDef(toolCall)]
        },
    },
    get_replay_vision_scan_results: {
        name: 'Read scan results',
        description: 'Read scan results for each recording in a Replay Vision scan, failures included',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Read the scan results'
            }
            return 'Reading the scan results...'
        },
    },
    retry_replay_vision_observation: {
        name: 'Retry a scan',
        description: 'Retry a scan on a recording whose observation failed',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Retried the scan'
            }
            return 'Retrying the scan...'
        },
    },
    get_replay_vision_quota: {
        name: 'Check Replay Vision credits',
        description: 'Check Replay Vision credits left in the monthly budget',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Checked Replay Vision credits'
            }
            return 'Checking Replay Vision credits...'
        },
    },
    create_replay_vision_scanner: {
        name: 'Create a scanner',
        description: 'Create a scanner that watches new recordings as they arrive',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created the scanner'
            }
            return 'Creating the scanner...'
        },
    },
    update_replay_vision_scanner: {
        name: 'Update a scanner',
        description: 'Update a scanner: turn it on or off, rename it, reword it, or change its sampling',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Updated the scanner'
            }
            return 'Updating the scanner...'
        },
    },
    list_replay_vision_scanners: {
        name: 'List scanners',
        description: 'List scanners in this project, with their ids, status and sampling',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'List scanners'
            }
            return 'List scanners...'
        },
    },
    delete_replay_vision_scanner: {
        name: 'Delete a scanner',
        description: 'Delete a scanner and every observation it produced',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Delete a scanner'
            }
            return 'Delete a scanner...'
        },
    },
    estimate_replay_vision_scanner: {
        name: 'Estimate scanner cost',
        description: 'Estimate scanner cost: recordings a month and the credits they take',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Estimate scanner cost'
            }
            return 'Estimate scanner cost...'
        },
    },
    label_replay_vision_observation: {
        name: 'Rate a result',
        description: 'Rate a result: tell Replay Vision whether a scanner got a recording right',
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Rate a result'
            }
            return 'Rate a result...'
        },
    },
    analyze_replay_vision_impact: {
        name: 'Measure impact',
        description: "Measure impact: how many sessions and people a scanner's findings affected",
        icon: iconForType('session_replay'),
        modes: [AgentMode.SessionReplay],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Measure impact'
            }
            return 'Measure impact...'
        },
    },
    create_survey: {
        name: 'Create surveys',
        description: 'Create surveys in seconds',
        product: Scene.Surveys,
        icon: iconForType('survey'),
        modes: [AgentMode.Survey],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created surveys'
            }
            return 'Creating surveys...'
        },
    },
    edit_survey: {
        name: 'Edit survey',
        description: 'Edit survey',
        product: Scene.Surveys,
        icon: iconForType('survey'),
        modes: [AgentMode.Survey],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Edited survey'
            }
            return 'Editing survey...'
        },
    },
    analyze_survey_responses: {
        name: 'Analyze survey responses',
        description: 'Analyze survey responses to extract themes and actionable insights',
        product: Scene.Surveys,
        icon: iconForType('survey'),
        modes: [AgentMode.Survey],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Analyzed survey responses'
            }
            return 'Analyzing survey responses...'
        },
    },
    create_message_template: {
        name: 'Create email templates',
        description: 'Create email templates from scratch or using a URL for inspiration',
        product: Scene.Workflows,
        icon: iconForType('workflows'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created email templates'
            }
            return 'Creating email templates...'
        },
    },
    fix_hogql_query: {
        name: 'Fix SQL',
        icon: iconForType('data_warehouse'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Fixed SQL'
            }
            return 'Fixing SQL...'
        },
    },
    filter_web_analytics: {
        name: 'Filter web analytics',
        description: 'Filter web analytics to analyze traffic patterns and user behavior',
        product: Scene.WebAnalytics,
        icon: iconForType('web_analytics'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Filtered web analytics'
            }
            return 'Filtering web analytics...'
        },
    },
    web_analytics_doctor: {
        name: 'Diagnose web analytics',
        description: 'Diagnose web analytics setup issues like missing pageviews or partial proxy coverage',
        product: Scene.WebAnalytics,
        icon: iconForType('web_analytics'),
        displayFormatter: (toolCall) => {
            return toolCall.status === 'completed' ? 'Diagnosed web analytics' : 'Diagnosing web analytics...'
        },
    },
    assess_heatmap: {
        name: 'Assess a heatmap',
        description:
            'Assess a heatmap for a page — click, rageclick, and scroll-depth data plus the elements under the hot spots — and recommend concrete changes',
        product: Scene.WebAnalytics,
        icon: iconForType('web_analytics'),
        displayFormatter: (toolCall) => {
            return toolCall.status === 'completed' ? 'Assessed heatmap' : 'Assessing heatmap...'
        },
    },
    summarize_website_interactions: {
        name: 'Summarize website interactions',
        description:
            "Summarize website interactions by fusing the aggregate heatmap with Replay Vision's per-session narratives — the numbers and the why",
        product: Scene.WebAnalytics,
        icon: iconForType('web_analytics'),
        displayFormatter: (toolCall) => {
            return toolCall.status === 'completed'
                ? 'Summarized website interactions'
                : 'Summarizing website interactions...'
        },
    },
    marketing_diagnose_setup: {
        name: 'Diagnose marketing analytics',
        description:
            'Diagnose marketing analytics setup with a health check across data sources, attribution, and conversion goals',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Diagnosed marketing analytics' : 'Diagnosing marketing analytics...',
    },
    marketing_explain_conversion_goal: {
        name: 'Explain a conversion goal',
        description:
            'Explain a conversion goal by showing which events drove its count, broken down by source and integration',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Explained conversion goal' : 'Explaining conversion goal...',
    },
    marketing_list_conversion_goals: {
        name: 'List conversion goals',
        description: 'List conversion goals with their last-30d performance',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Listed conversion goals' : 'Listing conversion goals...',
    },
    marketing_list_data_sources: {
        name: 'List marketing data sources',
        description: 'List marketing data sources with platform-side health for every connected ad integration',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Listed marketing data sources' : 'Listing marketing data sources...',
    },
    marketing_audit_utm: {
        name: 'Audit UTM tagging',
        description: 'Audit UTM tagging to find issues that prevent attribution to ad platforms',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Audited UTM tagging' : 'Auditing UTM tagging...',
    },
    marketing_suggest_conversion_goals: {
        name: 'Suggest conversion goals',
        description: 'Suggest conversion goals by ranking custom events that are good candidates',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Suggested conversion goals' : 'Suggesting conversion goals...',
    },
    marketing_suggest_utm_mappings: {
        name: 'Suggest UTM mappings',
        description:
            'Suggest UTM mappings by detecting unmatched utm_source values and proposing custom_source_mappings entries',
        product: Scene.MarketingAnalytics,
        icon: iconForType('marketing_analytics'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Suggested UTM mappings' : 'Suggesting UTM mappings...',
    },
    upsert_dashboard: {
        name: 'Create and edit dashboards',
        description: 'Create and edit dashboards with insights based on your requirements',
        product: Scene.Dashboard,
        icon: iconForType('dashboard'),
        displayFormatter: (toolCall) => {
            if (isObject(toolCall.args?.action) && toolCall.args?.action && 'dashboard_id' in toolCall.args?.action) {
                if (toolCall.status === 'completed') {
                    return 'Edited the dashboard'
                }
                return 'Editing the dashboard...'
            }

            if (toolCall.status === 'completed') {
                return 'Created the dashboard'
            }
            return 'Creating the dashboard...'
        },
    },
    create_feature_flag: {
        name: 'Create a feature flag',
        description: 'Create a feature flag in seconds',
        product: Scene.FeatureFlags,
        icon: iconForType('feature_flag'),
        modes: [AgentMode.Flags],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created feature flag'
            }
            return 'Creating feature flag...'
        },
    },
    create_experiment: {
        name: 'Create an experiment',
        description: 'Create an experiment in seconds',
        product: Scene.Experiments,
        icon: iconForType('experiment'),
        modes: [AgentMode.Flags],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created experiment'
            }
            return 'Creating experiment...'
        },
    },
    create_task: {
        name: 'Create a task',
        description: 'Create a task for an AI agent to execute coding changes in a repository',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created task'
            }
            return 'Creating task...'
        },
    },
    run_task: {
        name: 'Run a task',
        description: 'Run a task to trigger its execution',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Started task execution'
            }
            return 'Starting task...'
        },
    },
    get_task_run: {
        name: 'Get task status',
        description: 'Get task status including stage, progress, and any errors',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Got task status'
            }
            return 'Getting task status...'
        },
    },
    get_task_run_logs: {
        name: 'Get task logs',
        description: 'Get task logs for debugging and reviewing execution details',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Got task logs'
            }
            return 'Getting task logs...'
        },
    },
    list_tasks: {
        name: 'List tasks',
        description: 'List tasks in the current project with optional filtering',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Listed tasks'
            }
            return 'Listing tasks...'
        },
    },
    list_task_runs: {
        name: 'List task runs',
        description: 'List task runs for a specific task to see execution history',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Listed task runs'
            }
            return 'Listing task runs...'
        },
    },
    list_repositories: {
        name: 'List repositories',
        description: 'List repositories available via GitHub integration for creating tasks',
        product: Scene.TaskTracker,
        icon: iconForType('task'),
        flag: FEATURE_FLAGS.PHAI_TASKS,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Listed repositories'
            }
            return 'Listing repositories...'
        },
    },
    switch_mode: {
        name: 'Switch agent mode',
        description:
            'Switch agent mode to another specialized mode like product analytics, SQL, or session replay analysis',
        icon: <IconShuffle />,
        displayFormatter: (toolCall) => {
            if (toolCall.args.new_mode === AgentMode.Execution) {
                if (toolCall.status === 'completed') {
                    return 'Plan is complete, switching to execution mode'
                }
                return 'Finalizing plan...'
            } else if (toolCall.args.new_mode === AgentMode.Plan) {
                if (toolCall.status === 'completed') {
                    return 'Switched to plan mode'
                }
                return 'Switching to plan mode...'
            } else if (toolCall.args.new_mode === AgentMode.Research) {
                if (toolCall.status === 'completed') {
                    return 'Switched to research mode'
                }
                return 'Switching to research mode...'
            }
            // Use optional chaining since Plan and Research modes are not in MODE_DEFINITIONS
            const newMode = toolCall.args.new_mode as string
            const modeName =
                newMode in MODE_DEFINITIONS ? MODE_DEFINITIONS[newMode as keyof typeof MODE_DEFINITIONS].name : null
            const modeText = (modeName ? ` to the ${modeName} mode` : 'mode').toLowerCase()

            if (toolCall.status === 'completed') {
                return `Switched agent ${modeText}`
            }

            return `Switching agent ${modeText}...`
        },
    },
    execute_sql: {
        name: 'Write and tweak SQL',
        description: 'Write and tweak SQL right there',
        product: Scene.SQLEditor,
        icon: iconForType('insight/hog'),
        modes: [AgentMode.SQL],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Executed SQL'
            }
            return 'Writing a SQL query...'
        },
    },
    summarize_sessions: {
        // Retired tool. The entry stays so old conversations still render it, but it carries no `modes`:
        // `getToolsForMode` reads that field, and listing it would offer a tool nobody can call.
        name: 'Summarize sessions',
        description: 'Summarize sessions analyze real user behavior',
        icon: iconForType('session_replay'),
        displayFormatter: (toolCall) =>
            toolCall.status === 'completed' ? 'Summarized sessions' : 'Summarizing sessions...',
    },
    web_search: {
        name: 'Search the web', // Web search is a special case of a tool, as it's a built-in LLM provider one
        description: 'Search the web for up-to-date information',
        icon: <IconGlobe />,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                // The args won't be fully streamed initially, so we need to check if `query` is present
                return toolCall.args.query ? `Searched the web for **${toolCall.args.query}**` : 'Searched the web'
            }
            return toolCall.args.query ? `Searching the web for **${toolCall.args.query}**...` : 'Searching the web...'
        },
    },
    manage_memories: {
        name: 'Manage memories',
        description: 'Manage memories to store and retrieve persistent information',
        icon: <IconMemory />,
    },
    create_notebook: {
        name: 'Create a document',
        description: 'Create a document to write down your thoughts',
        icon: iconForType('notebook'),
        displayFormatter: (toolCall) => {
            if (toolCall.args.draft_content) {
                if (toolCall.status === 'completed') {
                    return 'Created a draft document'
                }
                return 'Creating a draft document...'
            }
            if (toolCall.status === 'completed') {
                return 'Created a document'
            }
            return 'Creating a document...'
        },
    },
    upsert_alert: {
        name: 'Manage alerts',
        description: 'Manage alerts to monitor insight metrics',
        icon: <IconNotification />,
        product: Scene.Insight,
        modes: [AgentMode.ProductAnalytics],
        displayFormatter: (toolCall) => {
            if (isObject(toolCall.args?.action) && 'alert_id' in toolCall.args.action) {
                return toolCall.status === 'completed' ? 'Updated alert' : 'Updating alert...'
            }
            return toolCall.status === 'completed' ? 'Created alert' : 'Creating alert...'
        },
    },
    diagnose_proxy: {
        name: 'Diagnose reverse proxy',
        description: 'Diagnose reverse proxy stuck or erroring states',
        icon: <IconCloud />,
        displayFormatter: (toolCall) => {
            return toolCall.status === 'completed' ? 'Diagnosed reverse proxy' : 'Diagnosing reverse proxy...'
        },
    },
    finalize_plan: {
        name: 'Finalize plan',
        description: 'Finalize plan',
        icon: iconForType('notebook'),
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Finalized plan'
            }
            return 'Finalizing plan...'
        },
    },
    search_llm_traces: {
        name: 'Search LLM traces',
        description: 'Search LLM traces to analyze model usage, costs, latency, and errors',
        icon: iconForType('llm_analytics'),
        modes: [AgentMode.AIObservability],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Searched LLM traces'
            }
            return 'Searching LLM traces...'
        },
    },
    create_ai_trace_parser: {
        name: 'Create custom parsers',
        description: 'Create custom parsers to control how AI observability events are displayed',
        icon: iconForType('llm_analytics'),
        clientExecuted: true,
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Created a custom parser'
            }
            return 'Writing a custom parser...'
        },
    },
    run_hog_eval_test: {
        name: 'Test evaluation',
        description: 'Test evaluation code against sample events',
        product: Scene.AIObservabilityEvaluation,
        icon: iconForType('llm_evaluations'),
        modes: [AgentMode.AIObservability],
        displayFormatter: (toolCall) => {
            if (toolCall.status === 'completed') {
                return 'Tested evaluation code'
            }
            return 'Testing evaluation code...'
        },
    },
    list_llm_skills: {
        name: 'List shared skills',
        description: 'List shared skills stored for this team',
        icon: <IconBook />,
        displayFormatter: (toolCall) =>
            skillStatusFormatter(toolCall, {
                completedLabel: 'Listed shared skills',
                pendingLabel: 'Listing shared skills',
            }),
    },
    get_llm_skill: {
        name: 'Load shared skill',
        description: 'Load shared skill body and file manifest',
        icon: <IconBook />,
        displayFormatter: (toolCall) =>
            skillStatusFormatter(toolCall, {
                completedLabel: 'Loaded shared skill',
                pendingLabel: 'Loading shared skill',
                nameArgKey: 'skill_name',
            }),
    },
    get_llm_skill_file: {
        name: 'Load shared skill file',
        description: 'Load shared skill file bundled in a skill',
        icon: <IconBook />,
        displayFormatter: (toolCall) =>
            skillStatusFormatter(toolCall, {
                completedLabel: 'Loaded skill file',
                pendingLabel: 'Loading skill file',
                nameArgKey: 'file_path',
            }),
    },
    create_llm_skill: {
        name: 'Create shared skill',
        description: 'Create shared skill to save a reusable workflow',
        product: Scene.AIObservability,
        icon: <IconBook />,
        modes: [AgentMode.AIObservability],
        displayFormatter: (toolCall) =>
            skillStatusFormatter(toolCall, {
                completedLabel: 'Created shared skill',
                pendingLabel: 'Creating shared skill',
                nameArgKey: 'name',
            }),
    },
    update_llm_skill: {
        name: 'Update shared skill',
        description: 'Update shared skill by publishing a new version',
        product: Scene.AIObservability,
        icon: <IconBook />,
        modes: [AgentMode.AIObservability],
        displayFormatter: (toolCall) =>
            skillStatusFormatter(toolCall, {
                completedLabel: 'Updated shared skill',
                pendingLabel: 'Updating shared skill',
                nameArgKey: 'skill_name',
            }),
    },
    archive_llm_skill: {
        name: 'Archive shared skill',
        description: 'Archive shared skill to hide it from suggestions',
        product: Scene.AIObservability,
        icon: <IconBook />,
        modes: [AgentMode.AIObservability],
        displayFormatter: (toolCall) =>
            skillStatusFormatter(toolCall, {
                completedLabel: 'Archived shared skill',
                pendingLabel: 'Archiving shared skill',
                nameArgKey: 'skill_name',
            }),
    },
}

export const MODE_DEFINITIONS: Record<
    Exclude<
        AgentMode,
        AgentMode.Plan | AgentMode.Execution | AgentMode.Research | AgentMode.Sandbox | AgentMode.UserInterview
    >,
    ModeDefinition
> = {
    [AgentMode.ProductAnalytics]: {
        name: 'Product analytics',
        description: 'Creates insights and dashboards to analyze your product data.',
        icon: iconForType('product_analytics'),
        scenes: new Set([Scene.Dashboards, Scene.Dashboard, Scene.Insight, Scene.SavedInsights]),
    },
    [AgentMode.SQL]: {
        name: 'SQL',
        description: 'Generates and executes SQL queries for your PostHog data and connected data warehouse sources.',
        icon: iconForType('sql_editor'),
        scenes: new Set([Scene.SQLEditor]),
    },
    [AgentMode.SessionReplay]: {
        name: 'Session replay',
        description: 'Analyzes session recordings and provides summaries and insights about user behavior.',
        icon: iconForType('session_replay'),
        scenes: new Set([
            Scene.Replay,
            Scene.ReplaySingle,
            Scene.ReplayPlaylist,
            Scene.ReplayFilePlayback,
            Scene.ReplaySettings,
        ]),
    },
    [AgentMode.ErrorTracking]: {
        name: 'Error tracking',
        description: 'Searches and analyzes error tracking issues to help you understand and fix bugs.',
        icon: iconForType('error_tracking'),
        scenes: new Set([Scene.ErrorTracking]),
    },
    [AgentMode.Survey]: {
        name: 'Surveys',
        description: 'Creates and analyzes surveys to collect user feedback.',
        icon: iconForType('survey'),
        scenes: new Set([Scene.Surveys, Scene.Survey]),
    },
    [AgentMode.Flags]: {
        name: 'Flags',
        description: 'Creates and manages feature flags and experiments.',
        icon: iconForType('feature_flag'),
        scenes: new Set([
            Scene.FeatureFlags,
            Scene.FeatureFlag,
            Scene.EarlyAccessFeature,
            Scene.EarlyAccessFeatures,
            Scene.Experiment,
            Scene.Experiments,
            Scene.ExperimentsSharedMetric,
            Scene.ExperimentsSharedMetrics,
        ]),
    },
    [AgentMode.AIObservability]: {
        name: 'AI observability',
        description: 'Analyzes LLM traces and writes evaluation code for AI observability.',
        icon: iconForType('llm_analytics'),
        scenes: new Set([
            Scene.AIObservability,
            Scene.AIObservabilityTrace,
            Scene.AIObservabilityEvaluation,
            Scene.AIObservabilityEvaluations,
            Scene.AIObservabilityDataset,
            Scene.AIObservabilityDatasets,
            Scene.AIObservabilityPlayground,
            Scene.AIObservabilityUsers,
        ]),
    },
    [AgentMode.CustomerAnalytics]: {
        name: 'Customer analytics',
        description:
            'Works with your customer accounts — assign owners, review notes and usage, and dig into account data.',
        icon: iconForType('cohort'),
        scenes: new Set([Scene.CustomerAnalytics, Scene.CustomerAnalyticsAccount]),
        flag: 'CUSTOMER_ANALYTICS_CSP',
    },
}

export const SPECIAL_MODES: Record<string, ModeDefinition> = {
    auto: {
        name: 'Auto',
        description:
            'Automatically selects the best mode based on your request. The tools that are available in all modes are listed below.',
        icon: <IconShuffle />,
    },
    plan: {
        name: 'Plan',
        description:
            "Creates a plan to guide the agent's actions and achieve your goals. The tools that are available in all modes are listed below.",
        icon: <IconNotebook />,
        beta: true,
    },
    research: {
        name: 'Research',
        description:
            'Answers complex questions using advanced reasoning models and more resources, taking more time to provide deeper insights.',
        icon: <IconBrain />,
        beta: true,
    },
    sandbox: {
        name: 'Sandbox',
        description: 'Spawns a cloud coding agent to work on the PostHog codebase.',
        icon: <IconCloud />,
        flag: 'PHAI_SANDBOX_MODE',
        alpha: true,
    },
}

/** Human-readable label for an agent or special mode value (e.g. `'product_analytics'` → `'Product analytics'`). */
export function getModeDisplayName(mode: string): string {
    return MODE_DEFINITIONS[mode as keyof typeof MODE_DEFINITIONS]?.name ?? SPECIAL_MODES[mode]?.name ?? mode
}

/** Get tools available for a specific agent mode */
export function getToolsForMode(mode: AgentMode): ToolDefinition[] {
    return Object.values(TOOL_DEFINITIONS).filter((tool) => tool.modes?.includes(mode))
}

/** Get default tools available in auto mode */
export function getDefaultTools(): ToolDefinition[] {
    const defaultTools = DEFAULT_TOOL_KEYS.map((key) => TOOL_DEFINITIONS[key])
    // Add web search after `search`
    defaultTools.splice(defaultTools.indexOf(TOOL_DEFINITIONS.search) + 1, 0, TOOL_DEFINITIONS.web_search)
    return defaultTools
}

export type SpecialMode = keyof typeof SPECIAL_MODES

export const AI_GENERALLY_CAN: { icon: JSX.Element; description: string }[] = [
    { icon: <IconAtSign />, description: 'Analyze and use attached context' },
    { icon: <IconMemory />, description: 'Remember project-level information' },
]

export const AI_GENERALLY_CANNOT: string[] = [
    'Access your source code or third‑party tools',
    'See data outside this PostHog project',
    'Guarantee correctness',
    'Order tungsten cubes',
]

export function getToolDefinitionFromToolCall(toolCall: EnhancedToolCall): ToolDefinition | null {
    const definition = getToolDefinition(toolCall.name)
    // Only use args.kind for subtool lookup if the parent tool has subtools
    if (definition?.subtools && typeof toolCall.args.kind === 'string') {
        return definition.subtools[toolCall.args.kind] ?? definition
    }
    return definition
}

export function getToolDefinition(identifier: string): ToolDefinition | null {
    const flatTools = Object.entries(TOOL_DEFINITIONS).flatMap(([key, tool]) => {
        if (tool.subtools) {
            return [{ ...tool, key }, ...Object.entries(tool.subtools).map(([key, value]) => ({ ...value, key }))]
        }
        return [{ ...tool, key }]
    })
    let definition = flatTools.find((tool) => tool.key === identifier)
    if (!definition) {
        return null
    }
    return definition
}