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.

7.0 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest'
import { z } from 'zod'

import { toMcpInputSchema } from '@/hono/tool-catalog'
import { isToolCallPayload, type ToolResultPayload } from '@/lib/build-tool-result'
import { RENDER_UI_RESOURCE_URI, URI_MAP } from '@/resources/ui-apps.generated'
import { createRenderUiTool, getRenderableToolNames, RENDER_UI_TOOL_NAME } from '@/tools/render-ui'
import { type Context, type Tool, type ZodObjectAny } from '@/tools/types'
import { APP_DATA_META_KEY } from '@/ui-apps/types'

const mockContext = {
    getDistinctId: async () => 'test-distinct-id',
} as unknown as Context

function makeTool(name: string, resourceUri?: string): Tool<ZodObjectAny> {
    return {
        name,
        title: name,
        description: `Tool ${name}`,
        schema: z.object({}),
        scopes: [],
        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false, readOnlyHint: true },
        handler: async () => ({ ok: true }),
        ...(resourceUri ? { _meta: { ui: { resourceUri } } } : {}),
    }
}

// Generated and opted-in custom apps are dispatchable; other custom apps are not.
const surveyTool = makeTool('survey-get', URI_MAP['survey'])
const queryTrendsTool = makeTool('query-trends', URI_MAP['query-results'])
const debugTool = makeTool('debug-tool', URI_MAP['debug'])
const plainTool = makeTool('plain-tool')

describe('render-ui tool', () => {
    it('only counts tools whose UI app has a reusable view as renderable', () => {
        expect(getRenderableToolNames([surveyTool, queryTrendsTool, debugTool, plainTool])).toEqual([
            'survey-get',
            'query-trends',
        ])
    })

    it('excludes non-read-only tools so render-ui cannot dispatch mutating tools', () => {
        const mutatingTool = makeTool('survey-launch', URI_MAP['survey'])
        mutatingTool.annotations.readOnlyHint = false
        expect(getRenderableToolNames([mutatingTool])).toEqual([])
    })

    it('returns null when no tool has a renderable UI app', () => {
        expect(createRenderUiTool([debugTool, plainTool], mockContext)).toBeNull()
    })

    it('restricts tool_name to the renderable tools', () => {
        const tool = createRenderUiTool([surveyTool, queryTrendsTool, debugTool, plainTool], mockContext)
        expect(tool).not.toBeNull()
        const schema = tool!.schema

        expect(schema.safeParse({ tool_name: 'survey-get', tool_input: { surveyId: 'abc' } }).success).toBe(true)
        expect(schema.safeParse({ tool_name: 'query-trends', tool_input: { kind: 'TrendsQuery' } }).success).toBe(true)
        // Non-UI and non-dispatchable custom-app tools are not valid enum members.
        expect(schema.safeParse({ tool_name: 'plain-tool' }).success).toBe(false)
        expect(schema.safeParse({ tool_name: 'debug-tool' }).success).toBe(false)
    })

    it('points trends explanations at explain-chart only when it can render it', () => {
        const explainChartTool = makeTool('explain-chart', URI_MAP['explain-chart'])

        expect(createRenderUiTool([queryTrendsTool, explainChartTool], mockContext)!.description).toContain(
            'end by rendering `explain-chart`'
        )
        expect(createRenderUiTool([queryTrendsTool], mockContext)!.description).not.toContain('explain-chart')
    })

    it('advertises the render-ui input schema', () => {
        const tool = createRenderUiTool([surveyTool, queryTrendsTool, debugTool, plainTool], mockContext)
        expect(tool).not.toBeNull()

        expect(toMcpInputSchema(tool!.schema)).toMatchInlineSnapshot(`
          {
            "properties": {
              "tool_input": {
                "additionalProperties": {},
                "description": "The generated input for that tool. The UI app uses it to fetch and render the visualization.",
                "propertyNames": {
                  "type": "string",
                },
                "type": "object",
              },
              "tool_name": {
                "description": "A tool that has a UI app — its visualization will be rendered for the user.",
                "enum": [
                  "survey-get",
                  "query-trends",
                ],
                "type": "string",
              },
            },
            "required": [
              "tool_name",
            ],
            "type": "object",
          }
        `)
    })

    it('emits a render directive payload with the envelope and render-ui resourceUri', async () => {
        const tool = createRenderUiTool([surveyTool, debugTool, plainTool], mockContext)!
        const result = (await tool.handler(mockContext, {
            tool_name: 'survey-get',
            tool_input: { surveyId: 'abc' },
        })) as ToolResultPayload

        expect(isToolCallPayload(result)).toBe(true)
        expect(result.structuredContent).toEqual({
            tool_name: 'survey-get',
            tool_input: { surveyId: 'abc' },
            app_key: 'survey',
            _analytics: { distinctId: 'test-distinct-id', toolName: RENDER_UI_TOOL_NAME },
        })
        expect(result._meta?.ui).toEqual({ resourceUri: RENDER_UI_RESOURCE_URI })
    })

    it('defaults tool_input to an empty object when omitted', async () => {
        const tool = createRenderUiTool([surveyTool], mockContext)!
        const result = (await tool.handler(mockContext, { tool_name: 'survey-get' })) as ToolResultPayload
        expect((result.structuredContent as Record<string, unknown>).tool_input).toEqual({})
    })

    it('carries preloaded data on app-only _meta and keeps it out of the model-visible result', async () => {
        const data = { id: 'abc', name: 'NPS' }
        const loadAppData = vi.fn().mockResolvedValue(data)
        const tool = createRenderUiTool([surveyTool], mockContext, undefined, loadAppData)!
        const result = (await tool.handler(mockContext, {
            tool_name: 'survey-get',
            tool_input: { surveyId: 'abc' },
        })) as ToolResultPayload

        expect(loadAppData).toHaveBeenCalledExactlyOnceWith('survey-get', { surveyId: 'abc' }, 'survey')
        expect(result._meta?.[APP_DATA_META_KEY]).toEqual(data)
        expect(JSON.stringify([result.content, result.structuredContent])).not.toContain('NPS')
    })

    it('leaves the app to fetch its own data when nothing was preloaded', async () => {
        const tool = createRenderUiTool([surveyTool], mockContext, undefined, async () => undefined)!
        const result = (await tool.handler(mockContext, { tool_name: 'survey-get' })) as ToolResultPayload
        expect(result._meta).not.toHaveProperty(APP_DATA_META_KEY)
    })

    it('never runs the inner tool handler itself', async () => {
        let innerCalled = false
        const spyTool = makeTool('survey-get', URI_MAP['survey'])
        spyTool.handler = async () => {
            innerCalled = true
            return { ok: true }
        }
        const tool = createRenderUiTool([spyTool], mockContext)!
        await tool.handler(mockContext, { tool_name: 'survey-get' })
        expect(innerCalled).toBe(false)
    })
})