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.

6.9 KB
Raw Blame
import { parseExecCall, parseExecCommand, POSTHOG_EXEC_TOOL_RE } from '../components/tool/posthogExecDisplay'
import type { PermissionRequestRecord } from '../types/streamTypes'

export interface ResolvedToolKey {
    resolvedKey: string
    innerToolName?: string
    innerInput?: Record<string, unknown>
    /** The MCP tool a Pi proxy call names while the server has not yet reported which MCP server answered it. */
    proxiedToolName?: string
}

type McpProxyCall = { kind: 'search'; query: string } | { kind: 'tool'; name: string }

export interface ResolvableToolCall {
    rawServerName: string
    rawToolName: string
    input: Record<string, unknown>
    meta?: unknown
}

export interface ResolvedToolCall extends ResolvedToolKey {
    claudeToolName?: string
}

/** Reads `_meta.claudeCode` off a tool frame's `_meta` without trusting its shape. */
export function getClaudeCodeMeta(meta: unknown): Record<string, unknown> | undefined {
    if (typeof meta !== 'object' || meta === null) {
        return undefined
    }
    const claudeCode = (meta as { claudeCode?: unknown }).claudeCode
    return typeof claudeCode === 'object' && claudeCode !== null ? (claudeCode as Record<string, unknown>) : undefined
}

/** Stable SDK tool name (`"Edit"`, `"TodoWrite"`) from `_meta.claudeCode.toolName`; undefined when absent. */
export function extractClaudeToolName(meta: unknown): string | undefined {
    const claudeCode = getClaudeCodeMeta(meta)
    return typeof claudeCode?.toolName === 'string' && claudeCode.toolName ? claudeCode.toolName : undefined
}

export function extractAgentToolName(meta: unknown): string | undefined {
    const posthog = typeof meta === 'object' && meta !== null ? (meta as { posthog?: unknown }).posthog : undefined
    if (typeof posthog === 'object' && posthog !== null) {
        const { toolName, mcp } = posthog as { toolName?: unknown; mcp?: unknown }
        if (typeof mcp === 'object' && mcp !== null) {
            const { server, tool } = mcp as { server?: unknown; tool?: unknown }
            if (typeof server === 'string' && server && typeof tool === 'string' && tool) {
                return `mcp__${server}__${tool}`
            }
        }
        if (typeof toolName === 'string' && toolName) {
            return toolName
        }
    }
    return extractClaudeToolName(meta)
}

/** The structured `_meta.posthog.mcpProxy` a Pi harness puts on a call made through its `mcp` proxy tool. */
function extractMcpProxyCall(meta: unknown): McpProxyCall | undefined {
    const posthog = typeof meta === 'object' && meta !== null ? (meta as { posthog?: unknown }).posthog : undefined
    const proxy =
        typeof posthog === 'object' && posthog !== null ? (posthog as { mcpProxy?: unknown }).mcpProxy : undefined
    if (typeof proxy !== 'object' || proxy === null) {
        return undefined
    }
    const { kind, query, name } = proxy as { kind?: unknown; query?: unknown; name?: unknown }
    if (kind === 'search' && typeof query === 'string' && query) {
        return { kind, query }
    }
    if (kind === 'tool' && typeof name === 'string' && name) {
        return { kind, name }
    }
    return undefined
}

/**
 * Resolves the registry key for a tool call. The single-exec `posthog` MCP server exposes one
 * outer `exec` tool; the inner tool name is parsed out of `rawInput.command`. Non-exec MCP tools
 * and built-ins look up by their wire name directly. Adapters can omit the wire `toolName`,
 * so the canonical name from adapter metadata is the fallback.
 */
export function resolveToolKey(
    serverName: string,
    toolName: string,
    input: Record<string, unknown>,
    agentToolName?: string
): ResolvedToolKey {
    const fullName = `mcp__${serverName}__${toolName}`
    const isPostHogExecTool =
        POSTHOG_EXEC_TOOL_RE.test(fullName) ||
        POSTHOG_EXEC_TOOL_RE.test(toolName) ||
        (agentToolName ? POSTHOG_EXEC_TOOL_RE.test(agentToolName) : false)

    if (isPostHogExecTool && typeof input.command === 'string') {
        const { verb, rest } = parseExecCommand(input.command)
        if (!verb) {
            return { resolvedKey: '__posthog_exec_unknown__' }
        }

        if (verb !== 'call') {
            return { resolvedKey: `__posthog_exec_${verb}__` }
        }

        // Resolve the inner sub-tool the same way the backend does (flags in any order). When it
        // can't be resolved, fall back to the unknown sentinel so the permission gate fails closed
        // instead of treating an unparsed `call` as a non-destructive tool.
        const { subTool, args } = parseExecCall(rest)
        if (!subTool) {
            return { resolvedKey: '__posthog_exec_unknown__' }
        }

        let innerInput: Record<string, unknown> = {}
        if (args) {
            try {
                innerInput = JSON.parse(args)
            } catch {
                return { resolvedKey: subTool, innerToolName: subTool }
            }
        }
        return { resolvedKey: subTool, innerToolName: subTool, innerInput }
    }

    return { resolvedKey: toolName || agentToolName || '' }
}

/** Resolves renderer-facing fields from a raw streamed tool invocation. */
export function resolveToolCall(toolCall: ResolvableToolCall): ResolvedToolCall {
    const claudeToolName = extractClaudeToolName(toolCall.meta)
    const agentToolName = extractAgentToolName(toolCall.meta)
    const mcp = agentToolName?.match(/^mcp__(.+?)__(.+)$/)
    // A Pi proxy call names the MCP tool before the server reports which server answered; the
    // descriptor arrives with the result and takes over above.
    const proxy = mcp ? undefined : extractMcpProxyCall(toolCall.meta)
    if (proxy?.kind === 'search') {
        return { resolvedKey: 'ToolSearch', innerInput: { query: proxy.query }, claudeToolName }
    }
    if (proxy) {
        return { resolvedKey: agentToolName ?? toolCall.rawToolName, proxiedToolName: proxy.name, claudeToolName }
    }
    return {
        ...resolveToolKey(
            mcp?.[1] ?? toolCall.rawServerName,
            mcp?.[0] ?? toolCall.rawToolName,
            toolCall.input,
            agentToolName
        ),
        claudeToolName,
    }
}

/**
 * The proposed inner tool input for a permission request — the args a tool renderer or a
 * `PermissionPreview` needs to preview what an approval will do. For a PostHog exec call this is
 * the command-embedded JSON args (`call <sub-tool> {…}`), falling back to the explicit `input` field
 * when the agent sends args out of band. Returns an empty object when neither is present.
 */
export function getPermissionRequestToolInput(record: PermissionRequestRecord): Record<string, unknown> {
    const resolved = resolveToolCall(record.rawToolCall)
    if (resolved.innerInput && Object.keys(resolved.innerInput).length > 0) {
        return resolved.innerInput
    }
    const explicit = (record.rawToolCall.input as { input?: unknown }).input
    return explicit && typeof explicit === 'object' && !Array.isArray(explicit)
        ? (explicit as Record<string, unknown>)
        : {}
}