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.

61.0 KB
Raw Blame
import type { CallToolResult, ListToolsResult } from '@modelcontextprotocol/sdk/types.js'

import type { PreparedToolCall } from '@posthog/mcp-analytics'

import {
    buildToolResultPayload,
    estimateResponseTokens,
    isToolCallPayload,
    toolResultAnalyticsProperties,
    type ToolResultPayload,
} from '@/lib/build-tool-result'
import { isEmptyToolResult } from '@/lib/empty-tool-result'
import {
    ExecCommandError,
    handleToolError,
    MissingOrganizationContextError,
    MissingProjectContextError,
    PinnedContextSwitchError,
    PostHogApiError,
    PostHogValidationError,
    ToolInputValidationError,
    MCPToolResultError,
    findPostHogPermissionError,
    findRecoverableApiError,
    hasTimeoutCause,
    isTimeoutError,
} from '@/lib/errors'
import { estimateTokens } from '@/lib/estimate-tokens'
import { resolveGatewayTools } from '@/lib/gateway-tools'
import { findIgnoredInputKeys, withIgnoredInputKeys } from '@/lib/ignored-input-keys'
import { challengeStepUpBeforeRun } from '@/lib/missing-scope'
import { getPostHogClient } from '@/lib/posthog'
import { sanitizeErrorToken } from '@/lib/posthog/analytics'
import { isPrivateScoutTrialTool } from '@/lib/tool-privacy'
import type { UiAppKey } from '@/resources/ui-apps.generated'
import {
    createExecTool,
    describeApiValidationError,
    describeExecCommand,
    describeInputShape,
    describeValidationError,
    formatInputValidationError,
    getDeprecatedToolRedirect,
    markNoncanonicalMetricRun,
    missingToolScopeError,
    parseExecCallInnerArgs,
    parseExecCallInnerToolName,
    repairArgumentNesting,
    UNRECOGNIZED_EXEC_TOKEN,
    type ExecCommandMeta,
    type ExecInnerCallProperties,
    type ExecInnerCallTracker,
} from '@/tools/exec'
import { EXECUTE_SQL_TOOL_NAME } from '@/tools/posthogAiTools/executeSql'
import { createRenderUiTool } from '@/tools/render-ui'
import { skillAnalyticsProperties, skillLookupMissProperties } from '@/tools/skills/analytics'
import { type BuiltInSkillHint, formatSkillLookupMiss, type SkillLookupMissKind } from '@/tools/skills/notFound'
import { getToolDefinitions } from '@/tools/toolDefinitions'
import type { Context, Tool, ZodObjectAny } from '@/tools/types'
import { readRenderUiData, renderUiDataRequest } from '@/ui-apps/apps/render-ui-data'

import {
    getModelMissingReason,
    trackExecuteSqlGeneration,
    trackToolCall,
    trackToolSpan,
    trackToolsList,
    type ToolCallAnalyticsMeta,
} from './analytics'
import {
    type GuidanceEngine,
    type GuidanceNotice,
    guidanceAnalyticsProperties,
    attachGuidanceNotice,
} from './guidance/engine'
import type { InstructionsBuilder } from './instructions'
import { getEffectiveMCPClientContext, getEffectiveMCPClientIdentity, resolveSessionKey } from './mcp-context'
import { toolCallDurationSeconds, toolCallsTotal, toolErrorsTotal } from './metrics'
import type { ResolvedState } from './request-state-resolver'
import type { SkillCatalogService } from './skill-catalog-service'
import type { ToolCatalog } from './tool-catalog'

interface ResolvedTool {
    name: string
    schema: ZodObjectAny
    handler: (ctx: Context, args: unknown) => Promise<unknown>
    _meta?: { ui?: { resourceUri?: string }; [key: string]: unknown } | undefined
}

interface ExecMetricState {
    innerToolName: string | undefined
    innerOutputFormat: ExecInnerCallProperties['output_format'] | undefined
    /** What the agent asked for, merged onto the event whichever verb ran. */
    commandMeta: ExecCommandMeta | undefined
    /**
     * The inner call's failure when the dispatcher recovered from it and returned
     * a normal result, so the canonical event still records the failure.
     */
    innerFailure: { error: unknown } | undefined
    /** Which kind of skill lookup missed, when the dispatcher rewrote a 404. */
    skillLookupMissKind: SkillLookupMissKind | undefined
    resultEmpty: boolean
}

/**
 * Whether a direct `tools/call` response should drop `structuredContent` and leave the
 * formatted table in the text channel to stand alone.
 *
 * CLI-mode clients read `content[].text`, so for them the structured copy only adds
 * tokens. A render-ui host in single-exec mode is the exception, because there
 * `buildAdvertisedTools` offers `exec` and `render-ui` only, and `handleToolCall` routes
 * both of those before this path. Any other tool name that reaches here is therefore the
 * render-ui app calling `callServerTool` to load its own data. That app reads
 * `structuredContent` and ignores the text channel, so dropping the structured payload
 * leaves it with nothing to draw, and it shows its error state instead of the chart. The
 * `handleToolsList` tests pin the roster this reasoning depends on.
 *
 * MCP gives the executor no way to prove that a call came from the app, so this reads
 * connection state instead of call provenance. In tools mode the model calls tools
 * directly, which makes the two indistinguishable, so suppression still applies there.
 * A UI app loaded that way still renders, because `buildToolResultPayload` moves the app
 * payload to the app-only `_meta` key whenever it suppresses `structuredContent` for a
 * tool that has a UI resource, without widening what the model reads.
 */
function shouldSuppressStructuredContent(args: {
    isCliModeEnabled: boolean
    useSingleExec: boolean
    renderUiEnabled: boolean
}): boolean {
    const isRenderUiHostInSingleExec = args.useSingleExec && args.renderUiEnabled
    return args.isCliModeEnabled && !isRenderUiHostInSingleExec
}

// A private response must not suppress another call sharing this JSON-RPC batch or token.
function stateForToolCall(state: ResolvedState, intent: string | undefined): ResolvedState {
    const scoped = { ...state, context: { ...state.context } }
    scoped.context.api = state.context.api.withAnalyticsSuppression(() => {
        scoped.suppressAnalytics = true
    })
    if (intent) {
        try {
            scoped.context.api = scoped.context.api.withIntent(intent)
        } catch {
            // Audit detail is optional; the per-call privacy boundary is not.
        }
    }
    return scoped
}

// Hooks run after SDK preparation to share its conversation handle and preserve per-call privacy suppression.
export interface ToolCallHooks {
    carriedContextHandle?: boolean
    resolveConversation?(conversationId: string): Promise<ResolvedState>
    beforeExecute(state: ResolvedState): Promise<Record<string, unknown> | undefined>
    afterExecute(state: ResolvedState, result: unknown): Promise<void>
}

export class ToolExecutor {
    private readonly catalog: ToolCatalog
    private readonly instructionsBuilder: InstructionsBuilder
    private readonly skillCatalogService: SkillCatalogService | undefined
    private readonly guidance: GuidanceEngine | undefined

    constructor(
        catalog: ToolCatalog,
        instructionsBuilder: InstructionsBuilder,
        skillCatalogService?: SkillCatalogService,
        guidance?: GuidanceEngine
    ) {
        this.catalog = catalog
        this.instructionsBuilder = instructionsBuilder
        this.skillCatalogService = skillCatalogService
        this.guidance = guidance
    }

    private async guidanceFor(
        state: ResolvedState,
        call: Parameters<GuidanceEngine['evaluate']>[1]
    ): Promise<GuidanceNotice | undefined> {
        return this.guidance?.evaluate(state, call)
    }

    async handleToolsList(state: ResolvedState): Promise<ListToolsResult> {
        const tools = this.injectAnalyticsParameters(this.buildAdvertisedTools(state), state.intentPrompt)

        void trackToolsList(
            tools.map((t) => t.name),
            state
        )

        return { tools }
    }

    // Guarded because analytics must never break `tools/list`.
    private injectAnalyticsParameters(tools: ListToolsResult['tools'], description?: string): ListToolsResult['tools'] {
        try {
            return getPostHogClient().prepareToolList(tools, description ? { context: { description } } : undefined)
        } catch {
            return tools
        }
    }

    private buildAdvertisedTools(state: ResolvedState): ListToolsResult['tools'] {
        if (state.useSingleExec) {
            const renderUiEntry = state.renderUiEnabled
                ? this.instructionsBuilder.buildRenderUiToolEntry(this.catalog.getPreBuiltEntries())
                : null
            return [this.instructionsBuilder.buildExecToolEntry(state), ...(renderUiEntry ? [renderUiEntry] : [])]
        }

        const nameSet = new Set(state.allTools.map((t) => t.name))
        const filteredTools = this.catalog.getPreBuiltEntries().filter((e) => nameSet.has(e.name))

        return filteredTools.map((entry) => {
            if (entry.name === EXECUTE_SQL_TOOL_NAME) {
                return {
                    ...entry,
                    description: this.instructionsBuilder.formatExecuteSqlDescription(),
                }
            }
            return entry
        })
    }

    private findOriginalTool(toolName: string, state: ResolvedState): ListToolsResult['tools'][number] | undefined {
        if (state.useSingleExec) {
            if (toolName === 'exec') {
                return this.instructionsBuilder.buildExecToolEntry(state)
            }
            if (toolName === 'render-ui' && state.renderUiEnabled) {
                return this.instructionsBuilder.buildRenderUiToolEntry(this.catalog.getPreBuiltEntries()) ?? undefined
            }
            return undefined
        }

        return this.buildAdvertisedTools(state).find((tool) => tool.name === toolName)
    }

    async handleToolCall(
        params: Record<string, unknown> | undefined,
        state: ResolvedState,
        hooks?: ToolCallHooks
    ): Promise<unknown> {
        const toolName = params?.name as string
        if (!toolName) {
            return { content: [{ type: 'text', text: 'Missing tool name' }], isError: true }
        }

        const rawArgs = (params?.arguments ?? {}) as Record<string, unknown>
        challengeStepUpForGatedTool(toolName, rawArgs, state)
        const originalTool = this.findOriginalTool(toolName, state)
        const rawRequestMeta = params?._meta
        const requestMeta =
            rawRequestMeta && typeof rawRequestMeta === 'object' && !Array.isArray(rawRequestMeta)
                ? (rawRequestMeta as Record<string, unknown>)
                : undefined
        const carriedContextHandle =
            hooks?.carriedContextHandle ??
            Boolean(state.requestContext.mcpSessionId || state.requestContext.mcpConversationId)
        const { analyticsMeta, args, preparedCall } = this.extractAnalyticsMetadata(
            toolName,
            rawArgs,
            originalTool,
            requestMeta,
            state.requestContext
        )
        // RequestContext shares this object so analytics follows the SDK's conversation handle.
        if (preparedCall?.conversationId) {
            const previousConversationId = state.requestContext.mcpConversationId
            state.requestContext.mcpConversationId = preparedCall.conversationId
            if (
                !state.requestContext.mcpSessionId &&
                preparedCall.conversationId !== previousConversationId &&
                hooks?.resolveConversation
            ) {
                // Bind the new handle before execution so this call and its retry share defaults.
                state = await hooks.resolveConversation(preparedCall.conversationId)
            }
        }
        const callState = stateForToolCall(state, analyticsMeta.intent)
        callState.carriedContextHandle = carriedContextHandle
        const callParams = { ...params, arguments: args }

        const targetToolName =
            toolName === 'exec' && typeof args.command === 'string'
                ? parseExecCallInnerToolName(args.command)
                : toolName
        const isContextSwitch = targetToolName === 'switch-project' || targetToolName === 'switch-organization'
        if (isContextSwitch && !carriedContextHandle) {
            return this.deliverConversationHandle(
                {
                    isError: true,
                    content: [
                        {
                            type: 'text',
                            text: 'Switch not applied. Retry with the returned `conversation_id` and include it on subsequent calls. If your client cannot retain it, pin the project or organization in the connection URL.',
                        },
                    ],
                },
                preparedCall
            )
        }

        const invitation = await hooks?.beforeExecute(callState)
        if (invitation) {
            return invitation
        }
        const result = await this.dispatchToolCall(toolName, callParams, callState, analyticsMeta)
        const delivered = this.deliverConversationHandle(result, preparedCall)
        await hooks?.afterExecute(callState, delivered)
        return delivered
    }

    // The agent can only echo a handle it has been given. One exit for every dispatch path,
    // and the SDK appends only on the call that minted the handle.
    private deliverConversationHandle(result: unknown, preparedCall: PreparedToolCall | undefined): unknown {
        if (!preparedCall?.conversationId) {
            return result
        }
        try {
            return getPostHogClient().prepareToolResult(result, preparedCall).result
        } catch {
            return result
        }
    }

    private async dispatchToolCall(
        toolName: string,
        callParams: Record<string, unknown>,
        state: ResolvedState,
        analyticsMeta: ToolCallAnalyticsMeta
    ): Promise<unknown> {
        if (toolName === 'exec') {
            if (state.viaMcpStore) {
                return { content: [{ type: 'text', text: 'Tool exec not found' }], isError: true }
            }
            return this.callExecTool(callParams, state, analyticsMeta)
        }

        if (toolName === 'render-ui') {
            // render-ui is only advertised to MCP Apps hosts; reject calls from others.
            if (!state.renderUiEnabled) {
                toolCallsTotal.inc({ tool: toolName, status: 'error' })
                return { content: [{ type: 'text', text: `Tool ${toolName} not found` }], isError: true }
            }
            return this.callRenderUiTool(callParams, state, analyticsMeta)
        }

        if (!state.allTools.some((t) => t.name === toolName)) {
            toolCallsTotal.inc({ tool: toolName, status: 'error' })
            const scopeGatedTool = state.findScopeGatedTool(toolName)
            if (scopeGatedTool) {
                const error = missingToolScopeError(scopeGatedTool, state.context, state.oauthClientId)
                return handleToolError(error, toolName, state.distinctId, undefined, state.suppressAnalytics)
            }
            const text = getDeprecatedToolRedirect(toolName, state.allTools) ?? `Tool ${toolName} not found`
            return { content: [{ type: 'text', text }], isError: true }
        }

        const preBuilt = this.catalog.getToolByName(toolName)
        if (!preBuilt) {
            toolCallsTotal.inc({ tool: toolName, status: 'error' })
            return { content: [{ type: 'text', text: `Tool ${toolName} not found` }], isError: true }
        }

        const tool = preBuilt.build()
        return this.callTool(
            {
                name: toolName,
                schema: tool.schema,
                handler: (ctx, args) => tool.handler(ctx, args),
                _meta: tool._meta,
            },
            callParams,
            state,
            analyticsMeta
        )
    }

    // execute-sql is the one tool whose advertised description is formatted per
    // request (the schema-discovery splice is assembled at render time) instead of served
    // from the catalog, on both the native tools/list path and exec's `info` output.
    // trackToolCall stamps the catalog text by default, so it needs the served text
    // for this tool or $mcp_tool_description records words the agent never saw.
    private servedToolDescription(toolName: string): string | undefined {
        if (toolName === EXECUTE_SQL_TOOL_NAME) {
            return this.instructionsBuilder.formatExecuteSqlDescription()
        }
        return undefined
    }

    // Guarded because analytics must never break `tools/call`. The SDK only strips
    // fields whose ownership it recorded while preparing the tool list.
    private extractAnalyticsMetadata(
        toolName: string,
        rawArgs: Record<string, unknown>,
        originalTool: ListToolsResult['tools'][number] | undefined,
        requestMeta: Record<string, unknown> | undefined,
        requestContext: ResolvedState['requestContext']
    ): {
        analyticsMeta: ToolCallAnalyticsMeta
        args: Record<string, unknown>
        preparedCall: PreparedToolCall | undefined
    } {
        try {
            const carriesContext = Boolean(requestContext.mcpSessionId || requestContext.mcpConversationId)
            const prepared = getPostHogClient().prepareToolCall(toolName, rawArgs, {
                originalTool,
                requestMeta,
                // Wrapper-only analytics hints cannot restore selections, so they must not suppress minting.
                sessionId: carriesContext ? resolveSessionKey(requestContext) : undefined,
            })
            return {
                analyticsMeta: {
                    intent: prepared.intent,
                    intentSource: prepared.intentSource,
                    llmModel: prepared.llmModel,
                    llmModelSource: prepared.llmModelSource,
                    llmModelMissingReason: prepared.llmModel ? undefined : getModelMissingReason(rawArgs.llm_model),
                },
                args: prepared.args ?? rawArgs,
                preparedCall: prepared,
            }
        } catch {
            return {
                analyticsMeta: { llmModelMissingReason: 'capture_error' },
                args: rawArgs,
                preparedCall: undefined,
            }
        }
    }

    private async callTool(
        tool: ResolvedTool,
        params: Record<string, unknown> | undefined,
        state: ResolvedState,
        analyticsMeta?: ToolCallAnalyticsMeta
    ): Promise<unknown> {
        const rawToolArgs = (params?.arguments ?? {}) as Record<string, unknown>
        // Computed on the raw input, before any alias is folded away by preprocess.
        const inputShape = inputShapeAnalyticsProperties(rawToolArgs, tool.schema)
        const firstPass = tool.schema.safeParse(rawToolArgs, { reportInput: true })
        const rewrapped = firstPass.success
            ? undefined
            : repairArgumentNesting(firstPass.error, rawToolArgs, tool.schema)
        const toolArgs = rewrapped ?? rawToolArgs
        const validation = rewrapped ? tool.schema.safeParse(toolArgs, { reportInput: true }) : firstPass
        if (!validation.success) {
            toolCallsTotal.inc({ tool: tool.name, status: 'validation_error' })
            const message = formatInputValidationError(tool.name, validation.error, toolArgs, tool.schema)
            // Emit the same errored `$mcp_tool_call` the exec path emits for an
            // identical rejection. Without it, direct-mode ('tools') schema
            // rejections are absent from analytics entirely — so every
            // exec-vs-direct comparison silently flatters direct mode, and
            // clients registered individually look error-free when they aren't.
            // Duration is 0: no handler ran (see `trackInnerCall`, same rule).
            const rejection = new ToolInputValidationError(
                message,
                describeValidationError(validation.error, tool.schema)
            )
            void trackToolCall(
                tool.name,
                0,
                true,
                state,
                {
                    ...inputShape,
                    ...errorAnalyticsProperties(classifyToolError(rejection, tool.name), rejection),
                },
                analyticsMeta,
                this.servedToolDescription(tool.name)
            )
            return {
                content: [{ type: 'text', text: message }],
                isError: true,
            }
        }

        const stop = toolCallDurationSeconds.startTimer({ tool: tool.name })
        const startMs = Date.now()

        // Which stored skill a skill-* read returned. Empty for every other tool, and
        // stamped only on success: a read that failed delivered no skill, so counting
        // it would let a deleted skill agents keep requesting read as a popular one.
        // The exec path stamps the same properties from its command string.
        const skillShape = skillAnalyticsProperties(tool.name, validation.data)

        try {
            const isContextSwitch = tool.name === 'switch-project' || tool.name === 'switch-organization'
            const previousContext = isContextSwitch
                ? await state.reqCtx.safelyGetAnalyticsContext(state.context)
                : undefined

            // Computed before the handler runs, so a failure here cannot follow a write that succeeded.
            const ignoredKeys = findIgnoredInputKeys(toolArgs, validation.data, tool.schema)
            const handlerResult = withIgnoredInputKeys(
                markNoncanonicalMetricRun(tool.name, await tool.handler(state.context, validation.data)),
                ignoredKeys
            )

            if (isContextSwitch) {
                void state.reqCtx.trackContextSwitchEvent(tool.name, state.context, previousContext)
            }

            toolCallsTotal.inc({ tool: tool.name, status: 'success' })
            stop({ status: 'success' })

            const duration = Date.now() - startMs
            const guidance = await this.guidanceFor(state, {
                toolName: tool.name,
                args: validation.data,
                isError: false,
                resultEmpty: isEmptyToolResult(handlerResult, tool.name),
            })

            let response: ToolResultPayload
            if (isToolCallPayload(handlerResult)) {
                response = handlerResult
            } else {
                const hasUiResource = !!tool._meta?.ui?.resourceUri
                const needsDistinctId = hasUiResource && typeof handlerResult !== 'string'
                const distinctId = needsDistinctId ? state.distinctId : undefined

                response = buildToolResultPayload({
                    handlerResult,
                    toolMeta: tool._meta,
                    toolName: tool.name,
                    params: validation.data,
                    includeAppData: state.clientProfile.consumer === 'posthog_ai',
                    suppressStructuredContentForFormattedResults: shouldSuppressStructuredContent({
                        isCliModeEnabled: state.clientProfile.isCliModeEnabled(),
                        useSingleExec: state.useSingleExec,
                        renderUiEnabled: state.renderUiEnabled,
                    }),
                    distinctId,
                    mcpClientName: getEffectiveMCPClientIdentity(state.requestContext, state.sessionContext)
                        .mcpClientName,
                })
            }

            void trackToolCall(
                tool.name,
                duration,
                false,
                state,
                {
                    ...inputShape,
                    ...skillShape,
                    input_tokens: estimateTokens(validation.data),
                    output_tokens: estimateResponseTokens(response),
                    ...toolResultAnalyticsProperties(response),
                    ...guidanceAnalyticsProperties(guidance),
                },
                analyticsMeta,
                this.servedToolDescription(tool.name)
            )

            if (tool.name === EXECUTE_SQL_TOOL_NAME) {
                void trackExecuteSqlGeneration(
                    tool.name,
                    validation.data,
                    state,
                    { durationMs: duration, isError: false },
                    analyticsMeta
                )
            }

            void trackToolSpan(tool.name, state, {
                durationMs: duration,
                isError: false,
                input: validation.data,
                output: response,
            })

            return attachGuidanceNotice(response, guidance)
        } catch (error: unknown) {
            toolCallsTotal.inc({ tool: tool.name, status: 'error' })
            stop({ status: 'error' })
            const classification = classifyToolError(error, tool.name)
            const guidance = await this.guidanceFor(state, {
                toolName: tool.name,
                args: validation.data,
                isError: true,
            })

            // A skill lookup that misses is not a failure the agent should read as
            // one. The exec dispatcher rewrites the same miss, and a tools-mode
            // client reaching this path must get the same answer — otherwise the
            // behavior changes with the client. Resolved here so the events below
            // record which kind of miss it was, and `handleToolError` adds nothing
            // to a 4xx that is lost by returning early: no recovery hint, no
            // exception capture.
            const lookupMiss = formatSkillLookupMiss(
                tool.name,
                error,
                validation.data as Record<string, unknown>,
                this.builtInSkillHint(state)
            )

            void trackToolCall(
                tool.name,
                Date.now() - startMs,
                true,
                state,
                {
                    ...inputShape,
                    ...errorAnalyticsProperties(classification, error),
                    ...(lookupMiss ? skillLookupMissProperties(lookupMiss.kind) : {}),
                    ...guidanceAnalyticsProperties(guidance),
                },
                analyticsMeta,
                this.servedToolDescription(tool.name)
            )

            const errorMessage = extractErrorMessage(error)
            if (tool.name === EXECUTE_SQL_TOOL_NAME) {
                void trackExecuteSqlGeneration(
                    tool.name,
                    validation.data,
                    state,
                    {
                        durationMs: Date.now() - startMs,
                        isError: true,
                        errorMessage,
                    },
                    analyticsMeta
                )
            }

            void trackToolSpan(tool.name, state, {
                durationMs: Date.now() - startMs,
                isError: true,
                errorMessage,
                input: validation.data,
            })

            if (lookupMiss) {
                return attachGuidanceNotice({ content: [{ type: 'text', text: lookupMiss.message }] }, guidance)
            }

            const sessionUuid = await sessionUuidForError(state)
            return attachGuidanceNotice(
                handleToolError(
                    error,
                    tool.name,
                    state.distinctId,
                    sessionUuid,
                    state.suppressAnalytics || isPrivateScoutTrialTool(tool.name)
                ),
                guidance
            )
        }
    }

    private async callExecTool(
        params: Record<string, unknown> | undefined,
        state: ResolvedState,
        analyticsMeta?: ToolCallAnalyticsMeta
    ): Promise<unknown> {
        const execMetrics: ExecMetricState = {
            innerToolName: undefined,
            innerOutputFormat: undefined,
            commandMeta: undefined,
            innerFailure: undefined,
            skillLookupMissKind: undefined,
            resultEmpty: false,
        }
        const resolved = this.resolveExecTool(state, execMetrics, analyticsMeta)

        const toolArgs = (params?.arguments ?? {}) as Record<string, unknown>

        // Which verb ran and which tool it targeted. Stamped on every exec event —
        // success and failure alike — so the discovery verbs stop collapsing into
        // one opaque `exec` bucket and an `info <tool>` can be linked to the
        // `call <tool>` that follows it. Read from the raw arguments so a rejected
        // wrapper records what it carried; the wrapper schema has no transform, so a
        // valid `command` is the same string either way.
        const execShape = execCommandAnalyticsProperties(toolArgs, state)
        // The inner tool's argument keys and any alias among them, read from the
        // command string the same way the dispatcher does. Only a `call` carries
        // arguments; the schema comes from this connection's catalog when the
        // target resolved to a tool in it.
        const execInputShape = execInputShapeAnalyticsProperties(toolArgs, execShape, state)
        const validation = resolved.schema.safeParse(toolArgs, { reportInput: true })
        if (!validation.success) {
            const wrapperInputShape = inputShapeAnalyticsProperties(toolArgs, resolved.schema)
            toolCallsTotal.inc({ tool: 'exec', status: 'validation_error' })
            const message = formatInputValidationError(resolved.name, validation.error)
            const rejection = new ToolInputValidationError(
                message,
                describeValidationError(validation.error, resolved.schema)
            )
            void trackToolCall(
                'exec',
                0,
                true,
                state,
                {
                    ...execShape,
                    ...wrapperInputShape,
                    ...errorAnalyticsProperties(classifyToolError(rejection, 'exec'), rejection),
                },
                analyticsMeta
            )
            return {
                content: [{ type: 'text', text: message }],
                isError: true,
            }
        }

        const startMs = Date.now()

        // In single-exec mode every transport-level call is `exec`, so `$mcp_tool_name`
        // would always read `exec` and hide which tool the agent actually invoked.
        // Attribute the canonical event to the inner tool that dispatched (captured by
        // `trackInnerCall` above) — keeping the same standard `$mcp_tool_name` the SDK
        // emits for direct calls, so exec-routed and direct calls share one vocabulary.
        // `$mcp_mode` already distinguishes single-exec from direct for anyone who needs
        // it. Non-`call` verbs (tools/info/search/schema) resolve no inner tool and stay
        // attributed to `exec`.
        const execToolName = (): string => execMetrics.innerToolName ?? 'exec'

        // Which stored skill an exec-routed read returned. Success only, unlike the
        // verb above: that records what the agent attempted, this records what it got.
        const execSkillShape = execSkillAnalyticsProperties(validation.data)

        try {
            const handlerResult = await resolved.handler(state.context, validation.data)
            const duration = Date.now() - startMs

            const response = isToolCallPayload(handlerResult)
                ? handlerResult
                : buildToolResultPayload({
                      handlerResult,
                      toolMeta: resolved._meta,
                      toolName: 'exec',
                      params: validation.data,
                      suppressStructuredContentForFormattedResults: state.clientProfile.isCliModeEnabled(),
                      distinctId: undefined,
                  })

            // A handler can return normally for a call that failed: a skill lookup
            // miss is rewritten so the agent does not read it as an outage. The
            // canonical event still records the failure, and must not stamp a skill
            // the store never delivered — a miss is not a read.
            const innerFailure = execMetrics.innerFailure
            const failureShape = innerFailure
                ? errorAnalyticsProperties(classifyToolError(innerFailure.error, execToolName()), innerFailure.error)
                : undefined
            const guidance = await this.guidanceFor(state, {
                toolName: execToolName(),
                execVerb: typeof execShape.$mcp_exec_verb === 'string' ? execShape.$mcp_exec_verb : undefined,
                args: execMetrics.innerToolName ? parseExecCallInnerArgs(validation.data.command) : validation.data,
                isError: innerFailure !== undefined,
                resultEmpty: execMetrics.resultEmpty,
            })

            void trackToolCall(
                execToolName(),
                duration,
                failureShape !== undefined,
                state,
                {
                    ...execShape,
                    ...execInputShape,
                    ...(failureShape ?? execSkillShape),
                    ...(execMetrics.skillLookupMissKind
                        ? skillLookupMissProperties(execMetrics.skillLookupMissKind)
                        : {}),
                    input_tokens: estimateTokens(validation.data),
                    output_tokens: estimateResponseTokens(response),
                    ...execMetrics.commandMeta,
                    ...(execMetrics.resultEmpty ? { mcp_result_empty: true } : {}),
                    ...toolResultAnalyticsProperties(response),
                    ...guidanceAnalyticsProperties(guidance),
                },
                analyticsMeta,
                this.servedToolDescription(execToolName())
            )

            return attachGuidanceNotice(response, guidance, {
                jsonOutput: execMetrics.innerOutputFormat === 'json',
            })
        } catch (error: unknown) {
            const metricTool = execToolName()
            const classification = classifyToolError(error, metricTool)
            const guidance = await this.guidanceFor(state, {
                toolName: metricTool,
                execVerb: typeof execShape.$mcp_exec_verb === 'string' ? execShape.$mcp_exec_verb : undefined,
                args: execMetrics.innerToolName ? parseExecCallInnerArgs(validation.data.command) : validation.data,
                isError: true,
            })
            if (!execMetrics.innerToolName) {
                // Match the inner-tool path, which labels rejected input `validation_error`.
                const status = classification.errorType === 'validation' ? 'validation_error' : 'error'
                toolCallsTotal.inc({ tool: 'exec', status })
            }

            void trackToolCall(
                metricTool,
                Date.now() - startMs,
                true,
                state,
                {
                    ...execShape,
                    ...execInputShape,
                    ...errorAnalyticsProperties(classification, error),
                    ...execMetrics.commandMeta,
                    ...guidanceAnalyticsProperties(guidance),
                },
                analyticsMeta,
                this.servedToolDescription(metricTool)
            )

            const sessionUuid = await sessionUuidForError(state)
            // Attribute the failure to the inner tool that actually ran (e.g. `query-logs`),
            // not the `exec` wrapper — so the agent-facing `[tool]` label and the 5xx
            // exception fingerprint point at the real source instead of collapsing every
            // exec-routed failure into one opaque `exec` bucket.
            return attachGuidanceNotice(
                handleToolError(
                    error,
                    metricTool,
                    state.distinctId,
                    sessionUuid,
                    state.suppressAnalytics ||
                        isPrivateScoutTrialTool(metricTool) ||
                        isPrivateScoutTrialTool(execShape.$mcp_exec_target_tool)
                ),
                guidance
            )
        }
    }

    /**
     * Third-party MCP tools for this caller, or none if the gateway can't be reached.
     * Swallows failures on purpose: a connected server having a bad day must not stop
     * PostHog's own tools from working.
     */
    private async gatewayToolsFor(state: ResolvedState): Promise<Tool<ZodObjectAny>[]> {
        const projectId = await state.context.stateManager.getProjectId().catch(() => undefined)
        if (!projectId) {
            return []
        }
        try {
            return await resolveGatewayTools(state.context, projectId)
        } catch (error) {
            console.warn('[gateway-tools] failed to resolve connected MCP tools', error)
            return []
        }
    }

    /**
     * What this connection knows about the built-in PostHog skill catalog.
     *
     * Read from the catalog the server loads at startup, not from the `learn`
     * catalog: that one is undefined exactly when the `learn` command is off, which
     * is the case where an agent told to load a built-in skill has nowhere else to
     * go. A catalog that never loaded reports every name as absent, so the message
     * falls back to the store's own.
     */
    private builtInSkillHint(state: ResolvedState): BuiltInSkillHint {
        const catalog = this.skillCatalogService?.getCatalog()
        return {
            isBuiltIn: (name) => catalog?.has(name) === true,
            learnAvailable: this.instructionsBuilder.execSkillsEnabled(state),
        }
    }

    private resolveExecTool(
        state: ResolvedState,
        execMetrics: ExecMetricState,
        analyticsMeta?: ToolCallAnalyticsMeta
    ): ResolvedTool {
        const commandReference = this.instructionsBuilder.buildExecCommandReference(state)

        const trackInnerCall: ExecInnerCallTracker = (toolName, properties) => {
            // Record which inner tool actually dispatched so `callExecTool` can attribute
            // the canonical `$mcp_tool_call` event to the real tool instead of the `exec`
            // dispatcher. The PostHog event is intentionally NOT emitted here: the wrapper
            // event (now relabelled to the inner tool name, with the inner tool's category
            // derived from it) already carries this call, so a second emit would double-count.
            execMetrics.innerToolName = toolName
            execMetrics.innerOutputFormat = properties.output_format
            if (!properties.success) {
                execMetrics.innerFailure = { error: properties.error }
            }
            execMetrics.skillLookupMissKind = properties.skill_lookup_miss_kind
            execMetrics.resultEmpty = properties.result_empty === true
            const status = properties.success ? 'success' : properties.validation_error ? 'validation_error' : 'error'
            toolCallsTotal.inc({ tool: toolName, status })
            // Mirror the native path: schema rejections never start a handler, so
            // they get no duration observation (`callTool` starts its timer only
            // after validation passes).
            if (!properties.validation_error) {
                toolCallDurationSeconds.observe({ tool: toolName, status }, properties.duration_ms / 1000)
            }
            const errorMessage = properties.validation_error
                ? properties.error_message
                : extractErrorMessage(properties.error)
            if (toolName === EXECUTE_SQL_TOOL_NAME && properties.input) {
                void trackExecuteSqlGeneration(
                    toolName,
                    properties.input,
                    state,
                    {
                        durationMs: properties.duration_ms,
                        isError: !properties.success,
                        errorMessage,
                    },
                    analyticsMeta
                )
            }
            void trackToolSpan(toolName, state, {
                durationMs: properties.duration_ms,
                isError: !properties.success,
                errorMessage,
                input: properties.input,
                output: properties.output,
            })
        }
        const clientContext = getEffectiveMCPClientContext(state.requestContext, state.sessionContext)

        // CLI `info execute-sql` returns the tool's static description from the catalog.
        // Override it with the same prompt tools-mode advertises, so the
        // information_schema schema-discovery steering matches across both modes.
        const execTools = state.allTools.map((tool) =>
            tool.name === EXECUTE_SQL_TOOL_NAME
                ? {
                      ...tool,
                      description: this.instructionsBuilder.formatExecuteSqlDescription(),
                  }
                : tool
        )

        const execTool = createExecTool(
            execTools,
            state.context,
            this.instructionsBuilder.buildExecToolDescription(state),
            commandReference,
            clientContext.mcpConsumer,
            trackInnerCall,
            state.scopeGatedTools,
            {
                isInlineExecUiHost: state.clientProfile.isInlineExecUiHost(),
                mcpClientName: getEffectiveMCPClientIdentity(state.requestContext, state.sessionContext).mcpClientName,
                learnCatalog: this.instructionsBuilder.buildExecLearnCatalog(
                    state,
                    this.skillCatalogService?.getCatalog()
                ),
                flagGatedTools: state.flagGatedTools,
                ...(state.heldTools ? { heldTools: state.heldTools } : {}),
                builtInSkillHint: this.builtInSkillHint(state),
                oauthClientId: state.oauthClientId,
                ...(state.gatewayToolsEnabled
                    ? {
                          gatewayToolsProvider: () => this.gatewayToolsFor(state),
                          gatewayToolFilter: state.gatewayToolFilter,
                      }
                    : {}),
                // A verb-only report lands first; `search` then reports again with its query
                // and counts. Merge so the richer report wins without losing the verb.
                trackCommand: (meta) => {
                    execMetrics.commandMeta = { ...execMetrics.commandMeta, ...meta }
                },
            }
        )

        return {
            name: 'exec',
            schema: execTool.schema,
            handler: (ctx, args) => execTool.handler(ctx, args as { command: string }),
            _meta: execTool._meta,
        }
    }

    /**
     * Runs the call the render-ui app would make for its data, through the normal dispatch so
     * scopes, validation and per-tool metrics apply. Any failure, or a preload slower than
     * `RENDER_UI_PRELOAD_TIMEOUT_MS`, leaves the app to fetch.
     */
    private async loadRenderUiAppData(
        toolName: string,
        toolInput: Record<string, unknown>,
        appKey: UiAppKey,
        state: ResolvedState,
        analyticsMeta: ToolCallAnalyticsMeta
    ): Promise<unknown> {
        const request = renderUiDataRequest(toolName, toolInput, appKey)
        const preload = this.dispatchToolCall(request.name, { arguments: request.arguments }, state, analyticsMeta)
            .then((result) => {
                const data = readRenderUiData(result as CallToolResult, appKey)
                return data.isError ? undefined : (data.structuredContent ?? undefined)
            })
            .catch(() => undefined)
        let timer: ReturnType<typeof setTimeout> | undefined
        const timeout = new Promise<undefined>((resolve) => {
            timer = setTimeout(() => resolve(undefined), RENDER_UI_PRELOAD_TIMEOUT_MS)
        })
        try {
            return await Promise.race([preload, timeout])
        } finally {
            clearTimeout(timer)
        }
    }

    private async callRenderUiTool(
        params: Record<string, unknown> | undefined,
        state: ResolvedState,
        analyticsMeta?: ToolCallAnalyticsMeta
    ): Promise<unknown> {
        const renderUiTool = createRenderUiTool(
            state.allTools,
            state.context,
            getEffectiveMCPClientIdentity(state.requestContext, state.sessionContext).mcpClientName,
            (toolName, toolInput, appKey) =>
                this.loadRenderUiAppData(toolName, toolInput, appKey, state, analyticsMeta ?? {})
        )
        if (!renderUiTool) {
            return {
                content: [{ type: 'text', text: 'render-ui is not available — no tool has a UI app' }],
                isError: true,
            }
        }

        const toolArgs = (params?.arguments ?? {}) as Record<string, unknown>
        // Same shape properties as every other tool call, so this event does not read
        // as a call that sent no arguments.
        const inputShape = inputShapeAnalyticsProperties(toolArgs, renderUiTool.schema)

        const validation = renderUiTool.schema.safeParse(toolArgs)
        if (!validation.success) {
            toolCallsTotal.inc({ tool: 'render-ui', status: 'validation_error' })
            // The agent keeps zod's own message; the event gets the value-free one `callTool` records.
            const rejection = new ToolInputValidationError(
                formatInputValidationError('render-ui', validation.error),
                describeValidationError(validation.error, renderUiTool.schema)
            )
            void trackToolCall(
                'render-ui',
                0,
                true,
                state,
                {
                    ...inputShape,
                    ...errorAnalyticsProperties(classifyToolError(rejection, 'render-ui'), rejection),
                },
                analyticsMeta
            )
            return { content: [{ type: 'text', text: `Invalid input: ${validation.error.message}` }], isError: true }
        }

        const stop = toolCallDurationSeconds.startTimer({ tool: 'render-ui' })
        const startMs = Date.now()
        try {
            const handlerResult = await renderUiTool.handler(state.context, validation.data)
            toolCallsTotal.inc({ tool: 'render-ui', status: 'success' })
            stop({ status: 'success' })
            void trackToolCall('render-ui', Date.now() - startMs, false, state, inputShape, analyticsMeta)
            // The handler always returns an exec-built payload (UI resourceUri + structuredContent).
            return handlerResult
        } catch (error: unknown) {
            toolCallsTotal.inc({ tool: 'render-ui', status: 'error' })
            stop({ status: 'error' })
            const classification = classifyToolError(error, 'render-ui')
            void trackToolCall(
                'render-ui',
                Date.now() - startMs,
                true,
                state,
                { ...inputShape, ...errorAnalyticsProperties(classification, error) },
                analyticsMeta
            )
            const sessionUuid = await sessionUuidForError(state)
            return handleToolError(error, 'render-ui', state.distinctId, sessionUuid, state.suppressAnalytics)
        }
    }
}

type ToolErrorType =
    | 'missing_context'
    | 'validation'
    | 'permission'
    | 'timeout'
    | 'memory_limit'
    | 'rate_limited'
    | 'api_5xx'
    | 'api_4xx'
    | 'internal'

interface ToolErrorClassification {
    errorType: ToolErrorType
    /** Upstream HTTP status, when the failure came from a PostHog API error. */
    status?: number
    /** Value-free descriptors of a schema rejection (offending field+code). */
    validationFields?: string[]
    /** Machine-readable leaf failure code: the API's validation error code or the exec rejection reason. */
    errorCode?: string
    /** Field path the API's validation error pointed at, array indexes normalized to `N`. */
    errorField?: string
}

/**
 * Buckets a thrown tool error into a low-cardinality category, increments the
 * Prometheus counter, and returns the classification so the caller can also
 * surface it on the `$mcp_tool_call` event (`$mcp_error_type` / `$mcp_error_status`).
 * Without that, the MCP analytics dashboard only sees the `$mcp_is_error`
 * boolean and can't break failures down by reason.
 */
function classifyToolError(error: unknown, toolName: string): ToolErrorClassification {
    const classification = resolveToolErrorClassification(error)
    toolErrorsTotal.inc({ tool: toolName, error_type: classification.errorType })
    return classification
}

// Runs first in a tool call, before analytics, guidance, interview recruitment or the tool itself,
// so a step-up client that replays the call after re-consent repeats nothing.
function challengeStepUpForGatedTool(toolName: string, args: Record<string, unknown>, state: ResolvedState): void {
    if (!state.supportsStepUp || state.viaMcpStore) {
        return
    }
    const targetToolName =
        toolName === 'exec' && typeof args.command === 'string' ? parseExecCallInnerToolName(args.command) : toolName
    if (!targetToolName || state.allTools.some((tool) => tool.name === targetToolName)) {
        return
    }
    const scopeGatedTool = state.findScopeGatedTool(targetToolName)
    if (scopeGatedTool) {
        challengeStepUpBeforeRun(scopeGatedTool.requiredScopes, state.supportsStepUp)
    }
}

function resolveToolErrorClassification(error: unknown): ToolErrorClassification {
    if (error instanceof MCPToolResultError) {
        const errorCode = error.errorCode ? sanitizeErrorToken(error.errorCode) : undefined
        return { errorType: error.errorType, ...(errorCode ? { errorCode } : {}) }
    }
    if (
        error instanceof MissingProjectContextError ||
        error instanceof MissingOrganizationContextError ||
        error instanceof PinnedContextSwitchError
    ) {
        return { errorType: 'missing_context' }
    }
    if (error instanceof ToolInputValidationError) {
        return {
            errorType: 'validation',
            ...(error.fields.length ? { validationFields: error.fields } : {}),
        }
    }
    // Agent-recoverable command mistakes, so keep them out of the `internal` rate
    // ops alerts on. `missing_scope` and `tool_not_granted` are the exceptions: no
    // input the agent sends fixes them, the grant has to change.
    if (error instanceof ExecCommandError) {
        return {
            errorType:
                error.reason === 'missing_scope' || error.reason === 'tool_not_granted' ? 'permission' : 'validation',
            errorCode: error.reason,
        }
    }
    if (findPostHogPermissionError(error)) {
        return { errorType: 'permission' }
    }
    if (hasTimeoutCause(error)) {
        return { errorType: 'timeout' }
    }

    const apiError = findRecoverableApiError(error)
    if (apiError instanceof PostHogValidationError) {
        const errorCode = apiError.code ? sanitizeErrorToken(apiError.code) : undefined
        const errorField = apiError.attr ? normalizeErrorField(apiError.attr) : undefined
        // Same descriptor property and format as a local schema rejection, so one
        // query covers both layers.
        return {
            errorType: 'validation',
            validationFields: describeApiValidationError(apiError.attr, apiError.code),
            ...(errorCode ? { errorCode } : {}),
            ...(errorField ? { errorField } : {}),
        }
    }
    if (apiError instanceof PostHogApiError && apiError.status === 429) {
        return { errorType: 'rate_limited', status: apiError.status }
    }
    if (apiError instanceof PostHogApiError && apiError.status >= 500) {
        return { errorType: 'api_5xx', status: apiError.status }
    }
    if (apiError instanceof PostHogApiError) {
        return { errorType: 'api_4xx', status: apiError.status }
    }
    return { errorType: 'internal' }
}

// Mirrors the SDK's MAX_ERROR_MESSAGE_LENGTH so `$mcp_error_message` stays within
// the bound external servers get when they pass `error` to the SDK.
const MAX_ERROR_MESSAGE_LENGTH = 2048

// Below the render-ui app's result watchdog (`DEFAULT_WAIT_TIMEOUT_MS`, 20s), so a slow
// query returns the render directive in time and the app fetches the data itself.
const RENDER_UI_PRELOAD_TIMEOUT_MS = 15_000

/**
 * Collapses array indexes in a DRF attr path (`actions__2__inputs__email`) to
 * `N` so one leaf failure mode groups to one value regardless of where in the
 * payload it occurred.
 */
function normalizeErrorField(attr: string): string | undefined {
    return sanitizeErrorToken(attr.replace(/(^|__)\d+(?=__|$)/g, '$1N'))
}

/**
 * Extracts a capturable message from a thrown value, restricted to an allowlist
 * of error classes whose message shape we control. `$mcp_error_message` is
 * readable by every analytics viewer in the project — not just the caller that
 * received the tool result — so arbitrary `Error.message`s and thrown strings
 * are never captured: tools echo caller input into them (document previews, SQL
 * fragments) and `PostHogApiError`'s default message embeds the upstream
 * response body. API errors are rebuilt from status + method + URL path instead.
 */
function extractErrorMessage(error: unknown): string | undefined {
    const raw = resolveSafeErrorMessage(error)
    if (!raw) {
        return undefined
    }
    // Strip control characters except newline/tab (multi-line validation errors stay readable)
    const sanitized = raw
        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
        .trim()
        .slice(0, MAX_ERROR_MESSAGE_LENGTH)
    return sanitized || undefined
}

function resolveSafeErrorMessage(error: unknown): string | undefined {
    if (error instanceof MCPToolResultError) {
        return `Tool failed: ${error.errorType}`
    }
    // Static recovery walkthroughs generated by our own constructors.
    if (
        error instanceof MissingProjectContextError ||
        error instanceof MissingOrganizationContextError ||
        error instanceof PinnedContextSwitchError
    ) {
        return error.message
    }
    // Documented value-free: offending field paths + issue codes, never input values.
    if (error instanceof ToolInputValidationError) {
        return error.message
    }
    // Value-free: the reason enum only. The dispatcher's human message can echo the
    // caller's tool name or a JSON-parser fragment, so it's never captured.
    if (error instanceof ExecCommandError) {
        return `Exec command rejected: ${error.reason}`
    }
    if (isTimeoutError(error)) {
        return 'Tool call timed out'
    }
    const apiError = findRecoverableApiError(error)
    if (apiError instanceof PostHogValidationError) {
        // `detail` is the raw API validation body; for query tools it echoes the caller's
        // offending HogQL/filter expression (`/query/` resolver errors quote the bad name),
        // so capture only the controlled code + field, never the free-text detail.
        const code = apiError.code ? `: ${apiError.code}` : ''
        const field = apiError.attr ? ` (field: ${apiError.attr})` : ''
        return `Validation error${code}${field}`
    }
    if (apiError instanceof PostHogApiError) {
        // Rebuilt summary: no response body, no query string.
        return `HTTP ${apiError.status} ${apiError.statusText} on ${apiError.method} ${safeUrlPath(apiError.url)}`
    }
    return undefined
}

function safeUrlPath(url: string): string {
    try {
        return new URL(url).pathname
    } catch {
        return ''
    }
}

/** The session lookup reads and writes Redis; an outage there must not replace the structured tool error. */
async function sessionUuidForError(state: ResolvedState): Promise<string | undefined> {
    try {
        return await state.reqCtx.getEffectiveSessionUuid(state.requestContext)
    } catch {
        return undefined
    }
}

/**
 * `$mcp_input_keys`: the safe top-level argument names the caller sent, on every
 * event, success and failure alike. Names only, never values (see `describeInputShape`).
 *
 * `$mcp_input_aliases_used`: which declared aliases the call relied on, as
 * `alias:canonical`, present only when at least one was. Both halves are names
 * the tool's own schema declares.
 */
function inputShapeAnalyticsProperties(
    input: unknown,
    schema: ResolvedTool['schema'] | undefined
): Record<string, unknown> {
    // `params.arguments` is an unvalidated cast until `safeParse` runs; only a plain
    // object carries argument names, and walking a string or an array here would build
    // one entry per character or element before the schema gets to reject it.
    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
        return {}
    }
    return describeInputShape(input, schema)
}

/** The target `describeExecCommand` recorded, when it resolved to a real tool name. */
function recordedTargetTool(execShape: Record<string, unknown>): string | undefined {
    const target = execShape.$mcp_exec_target_tool
    return typeof target === 'string' && target !== UNRECOGNIZED_EXEC_TOKEN ? target : undefined
}

/**
 * The exec-mode counterpart of `inputShapeAnalyticsProperties`: the inner arguments
 * live as JSON inside `command`, so they are parsed with the dispatcher's own parser.
 * Verbs other than `call` carry no arguments and get no keys. The schema is looked up
 * only among the tools this connection can see. A gated or retired target has no schema,
 * so every key it sent counts as undeclared and its aliases stay absent.
 */
function execInputShapeAnalyticsProperties(
    execArgs: unknown,
    execShape: Record<string, unknown>,
    state: ResolvedState
): Record<string, unknown> {
    const command = (execArgs as { command?: unknown } | undefined)?.command
    if (typeof command !== 'string' || execShape.$mcp_exec_verb !== 'call') {
        return {}
    }
    const innerArgs = parseExecCallInnerArgs(command)
    if (!innerArgs) {
        return {}
    }
    const target = recordedTargetTool(execShape)
    const schema = target ? state.allTools.find((tool) => tool.name === target)?.schema : undefined
    return inputShapeAnalyticsProperties(innerArgs, schema)
}

/**
 * Properties stamped onto an errored `$mcp_tool_call` so the dashboard can slice
 * failures by reason. `$mcp_error_type` aligns with the SDK's native field; the
 * SDK derives a generic type from the thrown error when none is supplied, and an
 * explicit value here overrides it. `$mcp_error_message` carries a sanitized,
 * allowlisted summary of the failure (see `extractErrorMessage`) so tool-quality
 * drill-downs can show what went wrong without persisting caller-derived text.
 * `$mcp_error_code` / `$mcp_error_field` carry the machine-readable leaf failure
 * mode (error code + normalized field path, never values) so validation failures
 * are measurable per field instead of one undifferentiated `validation` bucket.
 */
function errorAnalyticsProperties(classification: ToolErrorClassification, error: unknown): Record<string, unknown> {
    const message = extractErrorMessage(error)
    return {
        $mcp_error_type: classification.errorType,
        ...(classification.status !== undefined ? { $mcp_error_status: classification.status } : {}),
        ...(classification.validationFields?.length ? { $mcp_validation_fields: classification.validationFields } : {}),
        ...(classification.errorCode ? { $mcp_error_code: classification.errorCode } : {}),
        ...(classification.errorField ? { $mcp_error_field: classification.errorField } : {}),
        ...(message !== undefined ? { $mcp_error_message: message } : {}),
    }
}

/**
 * Properties describing the exec command itself: `$mcp_exec_verb` (which
 * dispatcher verb ran) and `$mcp_exec_target_tool` (the tool `info`/`schema`/
 * `call` named).
 *
 * `$mcp_tool_name` already carries the inner tool for a successful `call`, but
 * it reads `exec` for every other verb and for a `call` that never resolved — so
 * schema discovery, tool search, and a mistyped verb are indistinguishable, and
 * an `unknown_tool` rejection records nothing about what was attempted. Both
 * values are value-free by construction (see `describeExecCommand`): the verb comes
 * from the closed grammar and the target from the server's tool catalog, so a
 * token outside either is recorded as unrecognized rather than echoed.
 */
function execCommandAnalyticsProperties(execArgs: unknown, state: ResolvedState): Record<string, unknown> {
    const command = (execArgs as { command?: unknown } | undefined)?.command
    if (typeof command !== 'string') {
        return {}
    }
    const { verb, targetTool } = describeExecCommand(
        command,
        (name) =>
            state.allTools.some((t) => t.name === name) ||
            state.scopeGatedTools.some((t) => t.name === name) ||
            state.flagGatedTools.some((t) => t.name === name) ||
            Object.prototype.hasOwnProperty.call(getToolDefinitions(), name)
    )
    return {
        ...(verb !== undefined ? { $mcp_exec_verb: verb } : {}),
        ...(targetTool !== undefined ? { $mcp_exec_target_tool: targetTool } : {}),
    }
}

/**
 * The skill properties for an exec-routed read, recovered from the command string.
 *
 * In single-exec mode the inner tool's arguments never arrive as tool arguments —
 * they are JSON inside `command` — so the direct-mode wiring alone would miss the
 * skill reads that arrive this way, which is nearly all of them. Reads the command with the
 * dispatcher's own parsers so analytics sees exactly the arguments the handler runs.
 */
function execSkillAnalyticsProperties(execArgs: unknown): Record<string, unknown> {
    const command = (execArgs as { command?: unknown } | undefined)?.command
    if (typeof command !== 'string') {
        return {}
    }
    return skillAnalyticsProperties(parseExecCallInnerToolName(command), parseExecCallInnerArgs(command))
}