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.

117 KB
Raw Blame
import { stringify as stringifyYaml } from 'yaml'
import { z } from 'zod'

import { getToolInputProperties, type ShouldRecordInputKeyFn } from '@posthog/mcp-analytics'

import { classifyAuthMethod } from '@/lib/auth-method'
import { markExecPayload, buildToolResultPayload, estimateResponseTokens } from '@/lib/build-tool-result'
import { isPostHogCodeConsumer } from '@/lib/client-detection'
import { isEmptyToolResult } from '@/lib/empty-tool-result'
import {
    ExecCommandError,
    type ExecCommandErrorReason,
    findRecoverableApiError,
    PostHogApiError,
    ToolInputValidationError,
} from '@/lib/errors'
import { estimateTokens } from '@/lib/estimate-tokens'
import { GATEWAY_TOOL_SEPARATOR, isGatewayToolName } from '@/lib/gateway-tools'
import { findIgnoredInputKeys, withIgnoredInputKeys } from '@/lib/ignored-input-keys'
import { isChatGptAppConnection } from '@/lib/oauth-constants'
import type { RequestProperties } from '@/lib/request-properties'
import { formatResponse } from '@/lib/response'
import { API_KEY_CACHE_TTL_MS } from '@/lib/StateManager'
import { APP_DATA_META_KEY } from '@/ui-apps/types'

import { readParamAliases } from './cast-helpers'
import { type ExecLearnCatalog, QUALIFIED_IDENTIFIER, tokenizeLearnInput } from './exec-learn'
import { TOKEN_CHAR_LIMIT, listAvailablePaths, resolveSchemaPath, summarizeSchema } from './schema-utils'
import { type BuiltInSkillHint, formatSkillLookupMiss, type SkillLookupMissKind } from './skills/notFound'
import { isRegexPattern, searchToolsRanked, searchToolsRegex } from './tool-search'
import { getToolDefinitions, type FlagGatedTool, type ScopeGatedTool } from './toolDefinitions'
import {
    POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY,
    POSTHOG_INFORMATIONAL_RESPONSE_KEY,
    POSTHOG_META_KEY,
    type Context,
    type Tool,
    type ZodObjectAny,
} from './types'

/** Upper bound on the size of a `search` regex — wide enough for an anchored
 *  alternation of a whole toolset, the longest pattern an agent composes.
 *  Length is all it bounds: matching cost rides on the pattern's shape, and a
 *  dozen characters are enough to backtrack catastrophically. */
const MAX_SEARCH_PATTERN_LENGTH = 800

/** Advertised on `tools/list` and on the runtime Tool. OpenAI's plugin verifier
 *  requires these three hints (plus idempotent) to be present, not just defined
 *  on the handler side. `destructiveHint` stays false because every read goes
 *  through `exec` too: Claude Code asks for approval on each call to a tool
 *  marked destructive, even when the user set it to always allow. */
export const EXEC_TOOL_ANNOTATIONS = {
    destructiveHint: false,
    idempotentHint: false,
    openWorldHint: true,
    readOnlyHint: false,
} as const

/** One line telling the agent third-party tools exist and how to find them, for the
 *  `tools` listing. Returns undefined when nothing is connected. */
async function resolveConnectedSummary(
    resolveTools: () => Promise<Tool<ZodObjectAny>[]>,
    posthogToolCount: number
): Promise<string | undefined> {
    const combined = await resolveTools()
    const extra = combined.length - posthogToolCount
    if (extra <= 0) {
        return undefined
    }
    const servers = new Set(
        combined.slice(posthogToolCount).map((tool) => tool.name.split(GATEWAY_TOOL_SEPARATOR)[0] ?? '')
    )
    return `${extra} tool${extra === 1 ? '' : 's'} from ${servers.size} connected MCP server${servers.size === 1 ? '' : 's'} (${[...servers].sort().join(', ')}) are also callable — find them with "search <what you need>".`
}

/** Ranked (plain-word) search can match loosely on a common token like
 *  "create"; cap the returned names so a vague query can't dump the catalog. */
const MAX_RANKED_SEARCH_RESULTS = 25

const DATA_DOMAIN_TOOL_PREFIXES = ['billing-', 'web-analytics-', 'usage-metrics-', 'query-', 'marketing-']

const METRIC_RUN_TOOL_NAME = 'data-catalog-metric-run'
const APPROVED_METRIC_STATUS = 'approved'
const PROPOSED_METRIC_STATUS = 'proposed'

export function markNoncanonicalMetricRun(toolName: string, result: unknown): unknown {
    if (toolName !== METRIC_RUN_TOOL_NAME || result === null || typeof result !== 'object') {
        return result
    }
    const envelope = result as Record<string, unknown>
    const status = envelope.status
    const isDrifted = envelope.is_drifted === true
    if (status === APPROVED_METRIC_STATUS && !isDrifted) {
        return result
    }
    if (status === PROPOSED_METRIC_STATUS && !isDrifted) {
        return {
            NONCANONICAL: `status=proposed is_drifted=false. Not approved: use it only if its definition fits the question. If you use it, open the answer with '📝 **Proposed definition in your data catalog**: [<display_name>](<url>), not yet approved. Review it and approve it if it fits.', with the url from generate-app-url for '/data-catalog/metrics/{name}', and say in one sentence why you used it.`,
            ...envelope,
        }
    }
    if (isDrifted && (status === APPROVED_METRIC_STATUS || status === PROPOSED_METRIC_STATUS)) {
        const approval = status === APPROVED_METRIC_STATUS ? 'approved' : 'not yet approved'
        return {
            NONCANONICAL: `status=${status} is_drifted=true. Its source insight changed after this definition was saved, and this run used the saved definition. Use it only if that definition measures what the user asked. If you use it, open the answer with '⚠️ **Drifted definition in your data catalog**: [<display_name>](<url>), ${approval}, and its source insight changed after it was saved. Review it before you rely on this number.', with the url from generate-app-url for '/data-catalog/metrics/{name}', and say in one sentence why you used it.`,
            ...envelope,
        }
    }
    return {
        NONCANONICAL: `status=${String(status)} is_drifted=${String(isDrifted)}. Do not present this as the answer; derive from an approved metric, label the result noncanonical in \`context\`, and tell the reader plainly that the number is a one-off calculation rather than a saved definition.`,
        ...envelope,
    }
}

// A tool whose description happens to mention the search term says nothing about what the
// search was for: `search persons-` reaches query-logs that way. Only a name match counts.
function namesMatchingSearch(names: string[], term: string): string[] {
    if (isRegexPattern(term)) {
        try {
            const regex = new RegExp(term, 'i')
            return names.filter((name) => regex.test(name))
        } catch {
            return []
        }
    }
    const tokens = term.toLowerCase().split(/\s+/).filter(Boolean)
    return names.filter((name) => tokens.some((token) => name.toLowerCase().includes(token)))
}

function catalogDiscoveryHint(allTools: Tool<ZodObjectAny>[], nameMatches: string[]): string | undefined {
    const availableToolNames = new Set(allTools.map((tool) => tool.name))
    const hasMetricCatalog =
        availableToolNames.has('metric-list') &&
        availableToolNames.has('metric-describe') &&
        availableToolNames.has('data-catalog-metric-run')
    const hasDataDomainMatch = nameMatches.some((name) =>
        DATA_DOMAIN_TOOL_PREFIXES.some((prefix) => name.startsWith(prefix))
    )
    if (!hasMetricCatalog || !hasDataDomainMatch) {
        return undefined
    }
    return 'For a named business or telemetry measure, list the complete governed catalog with metric-list, inspect a candidate with metric-describe, then run an approved match with data-catalog-metric-run.'
}

type ExecSchema = ReturnType<typeof makeExecSchema>

export interface ExecInnerCallProperties {
    duration_ms: number
    success: boolean
    output_format: 'json' | 'text' | 'structured'
    error_message?: string
    /**
     * HTTP status when the failure was a typed PostHog API error — value-free,
     * safe for consumers that must not forward raw error messages.
     */
    error_status?: number
    /** Input rejected by the tool's schema before dispatch — no handler ran. */
    validation_error?: boolean
    /**
     * The thrown value itself. The dispatcher can turn a failure into a normal
     * return — a skill lookup miss is rewritten so the agent does not read it as
     * an outage — and then the wrapper never sees the exception. Carrying it lets
     * the wrapper classify and sanitize the failure exactly as it does for one
     * that reaches its catch block, instead of recording the call as a success.
     */
    error?: unknown
    /**
     * Estimated input/output tokens for the inner tool call. Carried so single-exec
     * mode attributes token usage to the real tool rather than the `exec` wrapper.
     */
    input_tokens?: number
    output_tokens?: number
    input?: Record<string, unknown>
    /**
     * The payload returned to the client, exactly as serialized. Consumed by the
     * `$ai_span` capture for data-catalog-relevant calls, which needs the tool's
     * result (e.g. which metrics a catalog lookup returned), not just its size.
     */
    output?: unknown
    /** Which kind of skill lookup missed, when the dispatcher rewrote a 404. */
    skill_lookup_miss_kind?: SkillLookupMissKind
    result_empty?: boolean
}

export type ExecInnerCallTracker = (toolName: string, properties: ExecInnerCallProperties) => void

/**
 * What the agent asked `exec` to do, for the `$mcp_tool_call` event.
 *
 * `call` is already attributed to the inner tool it dispatched, so the value here is in
 * the other verbs — above all `search`, whose query is the only record of what an agent
 * looked for. A search that matches nothing is otherwise invisible, which leaves the
 * question "which capability do people reach for that we don't have" unanswerable.
 */
export interface ExecCommandMeta {
    /** The verb the agent used: `help`, `search`, `info`, `schema`, `tools`, `learn`, `call`. */
    exec_verb: string
    /** The raw search query. Already bounded to MAX_SEARCH_PATTERN_LENGTH by the handler. */
    exec_search_query?: string
    /** How many tools matched, before the response is truncated — 0 is the interesting case. */
    exec_search_match_count?: number
    /** When a regex matched nothing, how many tools the word-ranked fallback returned instead. */
    exec_search_fallback_match_count?: number
    /** How many of those matches came from a connected third-party server. */
    exec_search_gateway_match_count?: number
    exec_learn_kind?: ExecLearnKind
    exec_learn_target?: string
}

export type ExecCommandTracker = (meta: ExecCommandMeta) => void

export type ExecLearnKind = 'search' | 'load' | 'list' | 'describe' | 'guide'

export function classifyLearnCommand(
    rest: string
): Pick<ExecCommandMeta, 'exec_learn_kind' | 'exec_search_query' | 'exec_learn_target'> {
    let tokens: string[]
    try {
        tokens = tokenizeLearnInput(rest)
    } catch {
        return {}
    }
    const [first, ...args] = tokens
    if (first === '-s') {
        return { exec_learn_kind: 'search', exec_search_query: args.join(' ').slice(0, MAX_SEARCH_PATTERN_LENGTH) }
    }
    if (first === '-d') {
        return { exec_learn_kind: 'describe' }
    }
    if (first === undefined || first === 'skills') {
        return { exec_learn_kind: 'list' }
    }
    if (first !== undefined && QUALIFIED_IDENTIFIER.test(first)) {
        const searchIndex = args.indexOf('-s')
        return {
            exec_learn_kind: 'load',
            exec_learn_target: first.slice(0, MAX_SEARCH_PATTERN_LENGTH),
            ...(searchIndex === -1
                ? {}
                : {
                      exec_search_query: args
                          .slice(searchIndex + 1)
                          .join(' ')
                          .slice(0, MAX_SEARCH_PATTERN_LENGTH),
                  }),
        }
    }
    return { exec_learn_kind: 'guide' }
}

export interface ExecToolOptions {
    requireDestructiveConfirmation?: boolean
    learnCatalog?: ExecLearnCatalog
    /**
     * Client is an inline-exec UI-app host that renders MCP UI apps on the exec
     * response (Claude Code). Gets the same UI-app payload treatment as the
     * PostHog Desktop consumer: structuredContent suppressed toward the model, app data
     * re-homed onto `_meta`. Computed from the client profile at the call site.
     */
    isInlineExecUiHost?: boolean
    mcpClientName?: string | undefined
    /**
     * Resolves the caller's third-party MCP tools (see `lib/gateway-tools.ts`). Awaited
     * lazily by the commands that need a tool roster, so a session that never reaches for
     * a connected server pays nothing for having one. Must not throw: a failing gateway
     * degrades to "no third-party tools", never to a broken `exec`.
     */
    gatewayToolsProvider?: () => Promise<Tool<ZodObjectAny>[]>
    gatewayToolFilter?: Pick<RequestProperties, 'tools' | 'features' | 'excludeTools'> | undefined
    /** Reports what the agent asked for, so non-`call` verbs stop being invisible. */
    trackCommand?: ExecCommandTracker
    /**
     * Tools a feature flag removed from this connection's catalog. Lets a call to
     * a retired name name its successor instead of reading as an unknown tool.
     */
    flagGatedTools?: FlagGatedTool[]
    /**
     * Lets a 404 from the project skills store say that the name belongs to the
     * built-in PostHog catalog instead. Built from the server's own catalog, not
     * from `learnCatalog`: that one is absent exactly when `learn` is off, which
     * is the case where an agent has no way to reach a built-in skill at all.
     */
    builtInSkillHint?: BuiltInSkillHint
    oauthClientId?: string | undefined
    /**
     * The tools a scout run with a picked tool list holds. A catalog or connected tool outside this
     * set is refused as `tool_not_granted`, so the agent does not search for another way to reach it.
     */
    heldTools?: ReadonlySet<string>
}

const CALL_USAGE = 'Usage: call [--json] [--confirm] <tool_name> [json_input]'

/**
 * Plain errors out of the learn catalog are agent mistakes — unknown names, bad
 * line ranges, empty queries — so type them to keep them out of the `internal`
 * bucket ops alerts on. Anything that already carries its own class (an API
 * failure, a source outage, an exec error) propagates untouched.
 */
function classifyLearnError(error: unknown): unknown {
    if (!(error instanceof Error) || error.constructor !== Error) {
        return error
    }
    const reason: ExecCommandErrorReason = error.message.startsWith('Unknown ') ? 'unknown_learn_topic' : 'usage'
    return new ExecCommandError(error.message, reason)
}

function makeExecSchema(commandReference: string): z.ZodObject<{ command: z.ZodString }> {
    return z.object({
        command: z.string().describe(commandReference),
    })
}

function parseCommand(input: string): { verb: string; rest: string } {
    const trimmed = input.trim()
    const idx = trimmed.indexOf(' ')
    if (idx === -1) {
        return { verb: trimmed, rest: '' }
    }
    return { verb: trimmed.slice(0, idx), rest: trimmed.slice(idx + 1).trim() }
}

/** A later line opening with one of these is what separates a batched request
 *  from a legitimately multi-line argument. */
const EXEC_VERBS = new Set(['help', 'learn', 'tools', 'search', 'info', 'schema', 'call'])

const EXEC_COMMAND_HELP: Record<string, string> = {
    help: 'help [command] — list commands or show usage for one command',
    tools: 'tools — list available tool names',
    search: 'search <words or regex_pattern> — find tools by name, title, or description',
    info: 'info [--json] <tool_name> — show a tool description and input schema',
    schema: 'schema <tool_name> [field_path] — inspect a tool input schema field',
    call: 'call [--json] [--confirm] <tool_name> [json_input] — invoke a tool',
}

const LEARN_COMMAND_HELP = 'learn <topic...> — load learning topics or list available topics'

function execHelp(command: string, learnEnabled: boolean): string {
    const commands = learnEnabled ? { ...EXEC_COMMAND_HELP, learn: LEARN_COMMAND_HELP } : EXEC_COMMAND_HELP
    if (!command) {
        return Object.values(commands).join('\n')
    }
    const help = commands[command]
    if (typeof help !== 'string') {
        // `help <prefix>` is a natural way to ask "what can I do with workflows", so the
        // refusal names the command that answers it rather than only listing the verbs.
        throw new ExecCommandError(
            `Unknown command: "${command}". Run "help" to list available commands, or "search ${command}" to find tools for it.`,
            'unknown_command'
        )
    }
    return help
}

/** Bounds on the rejection message, so a long batch or a large JSON body does
 *  not come back as a wall of text. */
const MAX_LISTED_BATCH_COMMANDS = 5
const MAX_LISTED_BATCH_COMMAND_LENGTH = 200

function firstToken(line: string): string {
    const trimmed = line.trim()
    const idx = trimmed.search(/\s/)
    return idx === -1 ? trimmed : trimmed.slice(0, idx)
}

/** Only `call` carries a body that may span lines, so it ends once that body is
 *  complete JSON. That keeps a pretty-printed payload from reading as a batch. */
function isCompleteCommand(command: string): boolean {
    const { verb, rest } = parseCommand(command)
    if (verb !== 'call') {
        return true
    }
    const { rest: jsonBody } = parseCommand(parseCallFlags(rest).rest)
    if (!jsonBody) {
        return true
    }
    try {
        JSON.parse(jsonBody)
        return true
    } catch {
        return false
    }
}

/** Returns undefined for a single command, so only a genuine batch is rejected. */
function splitBatchedCommands(command: string): string[] | undefined {
    const lines = command.split('\n')
    if (lines.length < 2 || !EXEC_VERBS.has(firstToken(lines[0] ?? ''))) {
        return undefined
    }

    const commands: string[] = []
    let current = lines[0] ?? ''
    for (const line of lines.slice(1)) {
        if (EXEC_VERBS.has(firstToken(line)) && isCompleteCommand(current)) {
            commands.push(current.trim())
            current = line
            continue
        }
        current = `${current}\n${line}`
    }
    if (commands.length === 0) {
        return undefined
    }
    commands.push(current.trim())
    return commands
}

function batchedCommandMessage(commands: string[]): string {
    const listed = commands.slice(0, MAX_LISTED_BATCH_COMMANDS)
    const more = commands.length - listed.length
    const lines = listed.map((entry) => {
        const flattened = entry.replace(/\s+/g, ' ')
        const shown =
            flattened.length > MAX_LISTED_BATCH_COMMAND_LENGTH
                ? `${flattened.slice(0, MAX_LISTED_BATCH_COMMAND_LENGTH)}...`
                : flattened
        return `- ${shown}`
    })
    if (more > 0) {
        lines.push(`- ...and ${more} more`)
    }
    return [
        `exec runs one command per request, and this request held ${commands.length}.`,
        'Send each one as its own exec call. You can issue them in parallel. Commands found:',
        ...lines,
    ].join('\n')
}

function parseCallFlags(input: string): { forceJson: boolean; confirmed: boolean; rest: string } {
    let rest = input.trim()
    let forceJson = false
    let confirmed = false

    while (rest) {
        const parsed = parseCommand(rest)
        if (parsed.verb === '--json') {
            forceJson = true
            rest = parsed.rest
            continue
        }
        if (parsed.verb === '--confirm') {
            confirmed = true
            rest = parsed.rest
            continue
        }
        break
    }

    return { forceJson, confirmed, rest }
}

const TRAILING_CALL_FLAG = /(?:^|\s)(--json|--confirm)$/

/** Reads `--json` and `--confirm` written after the tool name, before or after the JSON body.
 *  Agents put flags there because most CLIs accept them anywhere. No JSON value starts or ends
 *  with either token, so removing them never changes a valid body. */
function parseCallBodyFlags(input: string): { forceJson: boolean; confirmed: boolean; rest: string } {
    let { forceJson, confirmed, rest } = parseCallFlags(input)
    for (let match = TRAILING_CALL_FLAG.exec(rest); match; match = TRAILING_CALL_FLAG.exec(rest)) {
        forceJson ||= match[1] === '--json'
        confirmed ||= match[1] === '--confirm'
        rest = rest.slice(0, match.index).trimEnd()
    }
    return { forceJson, confirmed, rest }
}

// Extracts the inner tool name from an exec `call` command, e.g.
// "call my-tool {...}" → "my-tool". Returns undefined for other verbs or
// malformed input. Used by analytics to surface the real tool being invoked
// in single-exec mode, where the outer call always shows as `exec`.
export function parseExecCallInnerToolName(command: string): string | undefined {
    const { verb, rest } = parseCommand(command)
    if (verb !== 'call' || !rest) {
        return
    }
    const callArgs = parseCallFlags(rest).rest
    if (!callArgs) {
        return
    }
    const innerName = parseCommand(callArgs).verb
    return innerName || undefined
}

// Extracts the inner tool's JSON arguments from an exec `call` command, e.g.
// `call skill-get {"skill_name":"x"}` → `{ skill_name: 'x' }`. Sibling of
// parseExecCallInnerToolName, and deliberately mirrors how the `call` handler
// below reads the same command — a body-less call is `{}` there, so it is `{}`
// here. Returns undefined when no inner arguments exist to read: another verb,
// or a body that is not a JSON object. Analytics uses this because in
// single-exec mode the arguments never arrive as tool arguments, so a property
// derived only from those would miss nearly every skill read.
export function parseExecCallInnerArgs(command: string): Record<string, unknown> | undefined {
    const { verb, rest } = parseCommand(command)
    if (verb !== 'call' || !rest) {
        return
    }
    const callArgs = parseCallFlags(rest).rest
    if (!callArgs) {
        return
    }
    const jsonBody = parseCallBodyFlags(parseCommand(callArgs).rest).rest
    if (!jsonBody) {
        return {}
    }
    try {
        const parsed: unknown = JSON.parse(jsonBody)
        // Arrays and `null` are typeof 'object'; only a plain object holds arguments.
        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
            ? (parsed as Record<string, unknown>)
            : undefined
    } catch {
        return
    }
}

/** Verbs the dispatcher grammar accepts. A verb outside this set is what the
 *  `unknown_command` rejection fires on, and is recorded as unrecognized. */
const KNOWN_EXEC_VERBS = new Set(['help', 'learn', 'tools', 'search', 'info', 'schema', 'call'])

/** Verbs whose first positional argument names a tool. */
const TOOL_TARGETING_VERBS = new Set(['info', 'schema', 'call'])

/**
 * Recorded in place of a verb or tool name the server doesn't recognize. A token
 * the grammar rejected is caller text, and bounding its charset does not make it
 * value-free — an identifier-shaped secret survives sanitization intact. This file
 * already withholds `ExecCommandError`'s message from analytics for exactly this
 * reason (it echoes the caller's tool name); the rejection reason on the event says
 * which of the two failed, so the sentinel loses only the misspelling itself.
 */
export const UNRECOGNIZED_EXEC_TOKEN = 'unrecognized'

export interface ExecCommandShape {
    /** The dispatcher verb, or `unrecognized` when it isn't one we accept. */
    verb?: string
    /** The tool `info`/`schema`/`call` targeted, or `unrecognized` when the name
     *  resolves to nothing in our catalog. */
    targetTool?: string
}

/**
 * Describes an exec command for analytics: which verb ran, and which tool it
 * targeted. Both are value-free by construction — a verb from the closed grammar
 * and a tool name from our own catalog, never the caller's token (see
 * `describeValidationError` for the same constraint applied to schema rejections).
 *
 * Without this, every non-`call` verb lands in one undifferentiated `exec`
 * bucket: schema discovery is indistinguishable from tool search, and an
 * `unknown_command` rejection records no verb to diagnose. `targetTool` is what
 * links an `info <tool>` to the `call <tool>` that follows it.
 *
 * `isKnownToolName` decides whether a target resolves against the catalog this
 * connection can see; anything it rejects is recorded as
 * `UNRECOGNIZED_EXEC_TOKEN`.
 */
export function describeExecCommand(command: string, isKnownToolName: (name: string) => boolean): ExecCommandShape {
    const { verb: rawVerb, rest } = parseCommand(command)
    if (!rawVerb) {
        return {}
    }
    const verb = KNOWN_EXEC_VERBS.has(rawVerb) ? rawVerb : UNRECOGNIZED_EXEC_TOKEN
    if (!TOOL_TARGETING_VERBS.has(rawVerb)) {
        // Record the tool so a dropped `call` prefix is countable instead of hiding in
        // the unrecognized bucket with genuine typos.
        return isRecordableToolName(rawVerb, isKnownToolName) ? { verb, targetTool: rawVerb } : { verb }
    }
    if (!rest) {
        return { verb }
    }
    // The target must be parsed exactly as the dispatcher looks it up, or a
    // rejected command gets attributed to a valid tool. `call` strips its flags
    // then takes the first token; `schema` takes the first token. `info` is the
    // exception: it hands the entire remaining argument to `findTool` as an exact
    // name (after an optional `--json`), so `info execute-sql extra` looks up
    // "execute-sql extra", resolves to nothing, and records `unrecognized` — not
    // the `execute-sql` its first token would suggest.
    let target: string
    if (rawVerb === 'call') {
        target = parseCommand(parseCallFlags(rest).rest).verb
    } else if (rawVerb === 'info') {
        target = rest.replace(/^--json(\s+|$)/, '').trim()
    } else {
        target = parseCommand(rest).verb
    }
    if (!target) {
        return { verb }
    }
    return { verb, targetTool: isRecordableToolName(target, isKnownToolName) ? target : UNRECOGNIZED_EXEC_TOKEN }
}

/** Tool names we own, and can therefore record: the ones this connection can see,
 *  plus the removed ones kept only to redirect a call. A name outside both is the
 *  caller's own text. */
function isRecordableToolName(name: string, isKnownToolName: (name: string) => boolean): boolean {
    return isKnownToolName(name) || Object.prototype.hasOwnProperty.call(DEPRECATED_TOOL_REDIRECTS, name)
}

// Tools deleted from the MCP server. When the model attempts to call one,
// surface a targeted redirect to the replacement instead of dumping the full
// tool catalog. Keep the redirect text editorial — schemas don't carry
// "use X instead" guidance.
// A tool a feature flag removed still has a definition, so it declares its own
// successor through `superseded_by` and is answered by `flagGatedToolMessage`
// instead of by an entry here.
const DEPRECATED_TOOL_REDIRECTS: Record<string, (allTools: Tool<ZodObjectAny>[]) => string> = {
    // Removed in favor of SQL-based schema discovery via `system.information_schema.*`.
    'read-data-warehouse-schema': () =>
        'Tool "read-data-warehouse-schema" was removed in favor of SQL-based schema discovery. Use "execute-sql" against `system.information_schema.*` (`tables`, `columns`, `relationships`, `data_types`) — it scales to large catalogs and supports filtering/search (e.g. `WHERE description ILIKE \'%...%\'`). Consult the `querying-posthog-data` skill (a built-in local skill, when installed) for patterns.',
    'entity-search': (allTools) => {
        const base =
            'Tool "entity-search" was removed. Use "execute-sql" to search PostHog data via HogQL. Consult the `querying-posthog-data` skill (a built-in local skill, when installed) for system-table patterns (system.insights, system.dashboards, system.cohorts, ...).'
        const hasCatalog = allTools.some((t) => t.name === 'data-catalog-metric-run')
        return hasCatalog
            ? `${base} For governed business metrics, search \`system.information_schema.metrics\` instead of \`system.insights\`.`
            : base
    },
    'vision-scanners-suggest-tags': () =>
        'Tool "vision-scanners-suggest-tags" was removed. Set a classifier\'s tags yourself with "vision-scanners-update", or let "vision-scanners-draft" propose a full classifier config, tags included.',
    'llma-tagger-create': () =>
        'Tool "llma-tagger-create" was removed because taggers are deprecated. To tag or classify generations, use "llma-evaluation-create" with output_type="categorical", output_config.selection_mode="multiple", and one option per tag in output_config.options. Each option is { key, label }: the key is lowercase snake_case or kebab-case (for example "billing-issue"), and the label keeps the tag name. For an LLM tagger, set evaluation_type="llm_judge" with model_configuration (provider and model), and put the tagger prompt plus any tag descriptions in evaluation_config.prompt. For a Hog tagger, set evaluation_type="hog" with Hog source in evaluation_config.source that returns option keys. Run "info llma-evaluation-create" for the full schema.',
    'event-definitions-list': () =>
        'Tool "event-definitions-list" was removed. Use "read-data-schema" with input { "query": { "kind": "events" } } to list event definitions.',
    'properties-list': () =>
        'Tool "properties-list" was removed. Use "read-data-schema": { "query": { "kind": "event_properties", "event_name": "..." } } for event properties, or { "kind": "entity_properties", "entity": "person" | "session" | "group/<n>" } for entity properties.',
    'property-definitions': () =>
        'Tool "property-definitions" was removed. Use "read-data-schema" with the appropriate kind: "event_properties", "entity_properties", or "action_properties" — see its info schema for required fields.',
    'query-generate-hogql-from-question': () =>
        'Tool "query-generate-hogql-from-question" was removed. Write the HogQL yourself and run it via "execute-sql". Consult the `querying-posthog-data` skill (a built-in local skill, when installed) for HogQL patterns.',
    'query-run': (allTools) => {
        const queryTools = allTools
            .filter((t) => t.name.startsWith('query-'))
            .map((t) => `- ${t.name}: ${t.description.split('\n')[0]}`)
            .join('\n')
        return `Tool "query-run" was removed. Pick the typed query tool that matches your intent, or use "execute-sql" for arbitrary HogQL. Available query-* tools:\n${queryTools}`
    },
    // Folded into "inbox-reports-list", which already served the same endpoint.
    // Spell out the filter renames: the replacement declares no required
    // parameters, so an old array filter sent to it is silently dropped and the
    // caller gets an unfiltered list instead of an error.
    'self-driving-inbox-get': () =>
        'Tool "self-driving-inbox-get" was removed. Use "inbox-reports-list", which lists the same reports. For the old default, pass { "view": "actionable", "use_priority_preference": true, "sort": "priority", "limit": 10 }. The array filters became comma-separated strings: `priorities` is now `priority`, `source_products` is now `source_product`, and `scouts` is now `scout`. `view`, `scope`, `teammate_uuid`, `search`, and `offset` keep their names.',
    // The `experiment-get-all` -> `experiment-list` deprecation alias was deleted in #101042.
    // Same arguments, so the redirect only has to hand over the new name.
    'experiment-get-all': () =>
        'Tool "experiment-get-all" was removed. It was a deprecation alias for "experiment-list", which takes the same arguments. Call "experiment-list" instead.',
    // Replay Vision prompt suggestions were removed. Ratings now steer scanners without a review step.
    'vision-scanners-prompt-suggestions-apply': () =>
        'Tool "vision-scanners-prompt-suggestions-apply" was removed. Replay Vision no longer proposes prompt rewrites to review. Rate observations with "vision-observations-label-create" instead: ratings improve the scanner automatically. To change the prompt yourself, use "vision-scanners-update".',
    'vision-scanners-prompt-suggestions-current': () =>
        'Tool "vision-scanners-prompt-suggestions-current" was removed. Replay Vision no longer proposes prompt rewrites to review. Rate observations with "vision-observations-label-create" instead: ratings improve the scanner automatically. To change the prompt yourself, use "vision-scanners-update".',
    'vision-scanners-prompt-suggestions-dismiss': () =>
        'Tool "vision-scanners-prompt-suggestions-dismiss" was removed. Replay Vision no longer proposes prompt rewrites to review. Rate observations with "vision-observations-label-create" instead: ratings improve the scanner automatically. To change the prompt yourself, use "vision-scanners-update".',
    'vision-scanners-prompt-suggestions-generate': () =>
        'Tool "vision-scanners-prompt-suggestions-generate" was removed. Replay Vision no longer proposes prompt rewrites to review. Rate observations with "vision-observations-label-create" instead: ratings improve the scanner automatically. To change the prompt yourself, use "vision-scanners-update".',
    // Replay Vision deprecation aliases. Each replacement takes the same arguments.
    ...Object.fromEntries(
        [
            ['vision-observations-label-destroy', 'vision-observations-label-delete'],
            ['vision-observations-retrieve', 'vision-observations-get'],
            ['vision-quota-retrieve', 'vision-quota-get'],
            ['vision-scanners-estimate-create', 'vision-scanners-estimate'],
            ['vision-scanners-impact-retrieve', 'vision-scanners-impact-get'],
            ['vision-scanners-inline-scan-create', 'vision-scanners-inline-scan'],
        ].map(([removed, replacement]) => [
            removed,
            () =>
                `Tool "${removed}" was removed. It was a deprecation alias for "${replacement}", which takes the same arguments. Call "${replacement}" instead.`,
        ])
    ),
    // The legacy loops API was removed. Loops are workflows tagged origin_product "loops".
    ...Object.fromEntries(
        [
            ['loops-create', '"workflows-create"'],
            ['loops-create-execute', '"workflows-create"'],
            ['loops-create-prepare', '"workflows-create"'],
            ['loops-destroy', '"workflows-archive"'],
            ['loops-list', '"workflows-list"'],
            ['loops-partial-update', '"workflows-patch-graph" or "workflows-update"'],
            ['loops-preview-create', '"workflows-test-run"'],
            ['loops-retrieve', '"workflows-get"'],
            ['loops-review', '"workflows-create"'],
        ].map(([removed, replacement]) => [
            removed,
            () =>
                `Tool "${removed}" was removed. Loops run on workflows: read the building-loops skill, then use ${replacement} with origin_product "loops".`,
        ])
    ),
    'loops-run-create': () =>
        'Tool "loops-run-create" was removed. Loops run on workflows. "workflows-test-run" tests the graph one node at a time and mocks outbound calls by default; it does not start a real task run. To fire a loop for real, use Run now on an enabled schedule loop in PostHog Desktop, or wait for its trigger.',
    // Self-managed tables (reading a bucket in place) can no longer be created.
    'warehouse-tables-create': () =>
        'Tool "warehouse-tables-create" was removed. PostHog no longer links tables that read your bucket directly. To import bucket files, add an Amazon S3, Google Cloud Storage, Azure Blob, or Cloudflare R2 source with "data-warehouse-source-setup". Run "external-data-sources-wizard" for the required fields. To import a local file, upload it in the PostHog app at /data-warehouse/new-source?kind=FileUpload. The upload creates a FileUpload source.',
    'loops-runs-retrieve': () =>
        'Tool "loops-runs-retrieve" was removed. Loops run on workflows. For run history, call "tasks-list" with the hog_flow_id of the loop and archived set to all, then "tasks-runs-retrieve" on a run for its branch and output.',
}

export function getDeprecatedToolRedirect(toolName: string, allTools: Tool<ZodObjectAny>[]): string | undefined {
    return DEPRECATED_TOOL_REDIRECTS[toolName]?.(allTools)
}

/** The form caller keys and field names are matched on, so `date_from` reaches a field
 *  named `dateFrom`. These schemas mix the two spellings — a query's own fields are
 *  camelCase while its window's fields are snake_case — and a caller cannot tell which
 *  one a field uses without reading the schema. */
function matchableName(name: string): string {
    return name.replace(/[_-]/g, '').toLowerCase()
}

/** Where a loose key belongs: the object the wrapper declares that holds a field of that name. */
interface FieldPlacement {
    object: string
    field: string
}

/**
 * Indexes values by the name a caller might send for them.
 *
 * A name that two values would answer to is dropped: acting on it would guess which one the
 * caller meant, and a guess here runs a query the caller did not ask for.
 */
function byMatchableName<T>(entries: Iterable<readonly [string, T]>): Map<string, T> {
    const found = new Map<string, T>()
    const ambiguous = new Set<string>()
    for (const [field, value] of entries) {
        const name = matchableName(field)
        if (found.has(name)) {
            ambiguous.add(name)
            continue
        }
        found.set(name, value)
    }
    for (const name of ambiguous) {
        found.delete(name)
    }
    return found
}

/** Every name a caller might send for a field of an object the wrapper declares, such as
 *  `date_from` for `dateRange.date_from`. */
function subfieldPlacements(
    schema: ZodObjectAny,
    key: string,
    declared: ReadonlySet<string>
): Map<string, FieldPlacement> {
    return byMatchableName(
        [...declared].flatMap((object) =>
            [...wrapperFieldNames(schema, [key, object])].map(
                (field) => [field, { object, field }] as readonly [string, FieldPlacement]
            )
        )
    )
}

/**
 * Whether a field of the rebuilt call is already filled, counting an object and its own
 * fields as the same place.
 *
 * Two caller keys can name one field: `date_from` and `dateFrom` both answer to
 * `dateRange.date_from`, and `dateRange` and `date_range` both answer to `dateRange`. The
 * second one to arrive would overwrite the first, so it is left unplaced and the rebuild
 * stands down rather than choosing a value for the caller.
 */
function isTaken(taken: ReadonlySet<string>, destination: string): boolean {
    if (taken.has(destination)) {
        return true
    }
    const separator = destination.indexOf('.')
    if (separator > 0) {
        return taken.has(destination.slice(0, separator))
    }
    return [...taken].some((filled) => filled.startsWith(`${destination}.`))
}

/**
 * Sorts a flattened payload into the call the caller meant.
 *
 * Keys the outer schema declares beside the wrapper stay at the top level, and keys the
 * wrapper declares move inside it. A caller that flattens the payload usually flattens its
 * window one level further, so `date_from` arrives beside `limit` rather than inside
 * `dateRange`; a key like that goes back into the object that declares it.
 *
 * `unplaced` holds every key that belongs nowhere, and a caller that sent an object and one
 * of its fields loose puts that field there. Nothing is dropped to make a payload fit: a
 * wrapper that defaults its own fields parses `{"dateRagne": ...}` into a full set of
 * defaults, so dropping the key would run an unfiltered query and return plausible but wrong
 * rows instead of reporting the typo.
 */
function splitFlattenedPayload(
    input: Record<string, unknown>,
    key: string,
    schema: ZodObjectAny
): { rebuilt: Record<string, unknown>; nested: Record<string, unknown>; unplaced: string[] } {
    const siblings = topLevelFieldNames(schema)
    const declared = wrapperFieldNames(schema, [key])
    const fields = byMatchableName([...declared].map((field) => [field, field] as const))
    const placements = subfieldPlacements(schema, key, declared)
    // A name the wrapper declares itself is that field, never a field of one of its objects.
    for (const name of fields.keys()) {
        placements.delete(name)
    }
    const rebuilt: Record<string, unknown> = {}
    const nested: Record<string, unknown> = {}
    const objects = new Map<string, Record<string, unknown>>()
    const taken = new Set<string>()
    const unplaced: string[] = []
    for (const [name, value] of Object.entries(input)) {
        const field = fields.get(matchableName(name))
        const placement = placements.get(matchableName(name))
        if (name !== key && siblings.has(name)) {
            rebuilt[name] = value
        } else if (field !== undefined && !isTaken(taken, field)) {
            taken.add(field)
            nested[field] = value
        } else if (placement !== undefined && !isTaken(taken, `${placement.object}.${placement.field}`)) {
            taken.add(`${placement.object}.${placement.field}`)
            const object = objects.get(placement.object) ?? {}
            object[placement.field] = value
            objects.set(placement.object, object)
        } else {
            unplaced.push(name)
        }
    }
    for (const [name, value] of objects) {
        nested[name] = value
    }
    rebuilt[key] = nested
    return { rebuilt, nested, unplaced }
}

/**
 * Detects the caller sending a required object parameter's *contents* in place of
 * the parameter itself — `{dateRange, limit}` where `{query: {dateRange, limit}}`
 * was wanted. Zod strips the misplaced keys, so an unwrapped payload and an empty
 * one both surface as the same bare `missing required parameter`, and the caller
 * has no way to tell which mistake it made.
 *
 * Decided by re-parsing rather than by reading the schema, so it holds for any
 * wrapper shape: rebuild the call with `splitFlattenedPayload` and see whether the
 * schema accepts it. Confident when the rebuild either parses to something
 * non-empty, or fails only on paths *inside* the wrapper — both mean the nested
 * schema recognized the content. A payload of undeclared keys parses to `{}` and
 * is correctly rejected, as is a caller that sent nothing at all.
 */
function looksLikeUnwrappedPayload(
    issuePath: ReadonlyArray<PropertyKey>,
    input: unknown,
    schema: ZodObjectAny | undefined
): boolean {
    if (!schema || issuePath.length !== 1) {
        return false
    }
    const key = String(issuePath[0])
    if (!isRecord(input)) {
        return false
    }
    const keys = Object.keys(input)
    if (keys.length === 0 || keys.includes(key)) {
        return false
    }
    const { rebuilt, nested } = splitFlattenedPayload(input, key, schema)
    // A wrapper that declares no fields of its own, such as a loose or union shape,
    // places nothing, so read the raw payload under the key instead.
    const candidate = Object.keys(nested).length > 0 ? rebuilt : { [key]: input }

    const wrapped = schema.safeParse(candidate)
    if (wrapped.success) {
        const parsed = (wrapped.data as Record<string, unknown>)[key]
        return isRecord(parsed) && Object.keys(parsed).length > 0
    }
    // Every remaining complaint sits under the wrapper: the nested schema read the
    // content and rejected specific fields, so the nesting itself was the mistake.
    return wrapped.error.issues.every((issue) => issue.path.length > 1 && String(issue.path[0]) === key)
}

/** Bound on how many stray object keys the check tries, because each try costs a
 *  full parse of the tool's schema. A wrapped payload sits under a single key, so
 *  a call carrying more stray objects than this made a different mistake and falls
 *  through to the dropped-keys message. */
const MAX_WRAPPER_CANDIDATES = 3

/**
 * The mirror of `looksLikeUnwrappedPayload`: the caller nested a whole valid
 * payload under one key, for a tool that takes those fields at the top level.
 * Zod strips the undeclared wrapper, so the rejection names a field the caller
 * did send, one level down, and the caller has nothing to correct.
 *
 * Confident when the unwrapped value parses, or fails only on fields the wrapper
 * holds, because both mean the schema read the contents.
 */
function overWrappedPayloadKey(input: unknown, schema: ZodObjectAny | undefined): string | undefined {
    if (!schema || !isRecord(input)) {
        return undefined
    }
    const declared = topLevelFieldNames(schema)
    let tried = 0
    for (const [key, value] of Object.entries(input)) {
        if (declared.has(key) || !isRecord(value) || Object.keys(value).length === 0) {
            continue
        }
        if (tried === MAX_WRAPPER_CANDIDATES) {
            return undefined
        }
        tried += 1
        const unwrapped = schema.safeParse(value)
        if (unwrapped.success) {
            return key
        }
        const readsTheContents = unwrapped.error.issues.every(
            (issue) => issue.path.length > 0 && String(issue.path[0]) in value
        )
        if (readsTheContents) {
            return key
        }
    }
    return undefined
}

function acceptedTopLevelShape(nested: unknown, schema: ZodObjectAny | undefined): string {
    if (!schema || !isRecord(nested)) {
        return '{...}'
    }
    const declared = topLevelFieldNames(schema)
    const named = Object.keys(nested).filter((name) => declared.has(name))
    return named.length > 0 ? renderFieldShape(named) : '{...}'
}

/**
 * Rebuilds a flattened payload under the wrapper the schema wanted, so the call the caller meant runs.
 *
 * Naming the mistake in the rejection still costs a round trip, and the flattened shape is the most
 * common rejection on the tools built this way.
 *
 * `splitFlattenedPayload` decides where each key belongs. Returns undefined when a key belongs
 * nowhere, or when the rebuilt payload does not parse, so a payload malformed for some other
 * reason keeps its own rejection instead of being guessed at.
 */
export function rewrapFlattenedArguments(
    error: z.ZodError,
    input: unknown,
    schema: ZodObjectAny | undefined
): Record<string, unknown> | undefined {
    if (!schema || !isRecord(input) || error.issues.length !== 1) {
        return undefined
    }
    const issue = error.issues[0]!
    if (issue.code !== 'invalid_type' || !('input' in issue) || issue.input !== undefined) {
        return undefined
    }
    if (!looksLikeUnwrappedPayload(issue.path, input, schema)) {
        return undefined
    }

    const { rebuilt, nested, unplaced } = splitFlattenedPayload(input, String(issue.path[0]), schema)
    if (Object.keys(nested).length === 0 || unplaced.length > 0) {
        return undefined
    }

    return schema.safeParse(rebuilt).success ? rebuilt : undefined
}

/**
 * The mirror of `rewrapFlattenedArguments`: lifts a payload the caller nested under one
 * undeclared key, such as `{query: {series}}`, back to the top level the schema declares.
 *
 * A nested `query` object is the natural shape for a query tool, and callers keep sending
 * it even when the description says not to, so the rejection alone costs a round trip.
 *
 * Returns undefined when the wrapper or its siblings carry a key the schema does not
 * declare, because the parse would drop that key without a word, or when the lifted
 * payload does not parse.
 */
export function unwrapOverWrappedArguments(
    input: unknown,
    schema: ZodObjectAny | undefined
): Record<string, unknown> | undefined {
    const key = overWrappedPayloadKey(input, schema)
    if (!schema || !key || !isRecord(input)) {
        return undefined
    }
    const inner = input[key] as Record<string, unknown>
    const siblings = Object.fromEntries(Object.entries(input).filter(([name]) => name !== key))
    const declared = topLevelFieldNames(schema)
    if (Object.keys(siblings).some((name) => !declared.has(name))) {
        return undefined
    }
    if (Object.keys(inner).some((name) => !declared.has(name) || name in siblings)) {
        return undefined
    }
    const unwrapped = { ...siblings, ...inner }
    return schema.safeParse(unwrapped).success ? unwrapped : undefined
}

/** Repairs a call whose payload sits one level off from where the schema wants it, in either direction. */
export function repairArgumentNesting(
    error: z.ZodError,
    input: unknown,
    schema: ZodObjectAny | undefined
): Record<string, unknown> | undefined {
    return rewrapFlattenedArguments(error, input, schema) ?? unwrapOverWrappedArguments(input, schema)
}

function topLevelFieldNames(schema: ZodObjectAny): ReadonlySet<string> {
    const root = inputJsonSchema(schema)
    const properties = isRecord(root) ? root['properties'] : undefined
    return new Set(isRecord(properties) ? Object.keys(properties) : [])
}

/**
 * The field names the parameter at `path` declares directly, including the fields of
 * each variant when it is a union (`read-data-schema` keys its shape off a `kind`
 * discriminator). Composition keywords are walked one level at each step; nothing
 * deeper is collected, because only the caller's own keys are matched against this set.
 */
function wrapperFieldNames(schema: ZodObjectAny, path: readonly string[]): ReadonlySet<string> {
    const root = inputJsonSchema(schema)
    let nodes = isRecord(root) ? [root] : []
    for (const key of path) {
        nodes = nodes
            .flatMap((node) => [node, ...variantsOf(node)])
            .map((node) =>
                isRecord(node['properties']) ? (node['properties'] as Record<string, unknown>)[key] : undefined
            )
            .filter(isRecord)
    }
    const names = new Set<string>()
    for (const node of nodes.flatMap((node) => [node, ...variantsOf(node)])) {
        const fields = node['properties']
        if (isRecord(fields)) {
            for (const name of Object.keys(fields)) {
                names.add(name)
            }
        }
    }
    return names
}

/** An object shape written from field names alone, capped, with every value
 *  elided, so the message carries the tool's vocabulary and no caller input. */
function renderFieldShape(names: readonly string[]): string {
    const shown = names.slice(0, MAX_KEYS_NAMED).map((name) => `"${name}": ...`)
    if (names.length > MAX_KEYS_NAMED) {
        shown.push('...')
    }
    return `{${shown.join(', ')}}`
}

function variantsOf(node: Record<string, unknown>): Record<string, unknown>[] {
    return ['anyOf', 'oneOf', 'allOf']
        .flatMap((keyword) => (Array.isArray(node[keyword]) ? (node[keyword] as unknown[]) : []))
        .filter(isRecord)
}

/**
 * Renders the shape the tool would have accepted, by nesting the caller's own
 * keys under the wrapper they omitted: `{"query": {"dateRange": ..., "limit": ...}}`.
 *
 * A caller told only to "resend them as {"query": {...}}" has to work out which
 * of its fields belong inside, and the reports behind this said so — they asked
 * for one valid input shape at the point of rejection. Echoing the keys back in
 * place answers that without a second `info` call.
 *
 * Only keys the wrapper itself declares are named, so the rendered shape is the
 * tool's own vocabulary rather than the caller's, and values are always elided.
 * The message is returned to the caller and recorded as the analytics error
 * message, so it must carry no input. Falls back to `{...}` when no key matches.
 * `unplaced` names the keys that fit nowhere, which the shape cannot show.
 */
function acceptedWrapperShape(
    key: string,
    input: unknown,
    schema: ZodObjectAny | undefined
): { shape: string; unplaced: string[] } {
    if (!schema || !isRecord(input)) {
        return { shape: `{"${key}": {...}}`, unplaced: [] }
    }
    const { rebuilt, nested, unplaced } = splitFlattenedPayload(input, key, schema)
    const named = Object.keys(nested)
    // Siblings ride along: a caller that copies the shape without them loses the `name` or
    // the baseline window it sent, and its retry asks a different question.
    const fields = [
        `"${key}": ${named.length > 0 ? renderFieldShape(named) : '{...}'}`,
        ...Object.keys(rebuilt)
            .filter((sibling) => sibling !== key)
            .slice(0, MAX_KEYS_NAMED)
            .map((sibling) => `"${sibling}": ...`),
    ]
    return { shape: `{${fields.join(', ')}}`, unplaced }
}

/**
 * Names the top-level keys a non-strict schema dropped, so a caller told `id` is
 * missing can see that the key it did send — `scanner_id` — was discarded rather
 * than read. Without this the caller is told only that a parameter it never used
 * is missing, has nothing to correct, and retries the same call.
 *
 * Reports only that the keys were not accepted. It deliberately does not claim
 * one of them was meant as the missing parameter: matching `scanner_id` to a
 * missing `id` by name holds on `vision-scanners-get`, where the value is right
 * and only the name is wrong, but on a tool keyed by an observation id the same
 * key carries the wrong value entirely, and advising a rename would send the
 * caller further off course. Which key to use instead belongs in the tool's
 * description, where it can say so per tool.
 *
 * Returns key names only, never values — the message is returned to the caller
 * and recorded as the analytics error message.
 */
function undeclaredKeys(input: unknown, schema: ZodObjectAny | undefined): string[] {
    if (!schema || typeof input !== 'object' || input === null || Array.isArray(input)) {
        return []
    }
    const declared = declaredPropertyNames(schema)
    return Object.keys(input).filter((key) => !declared.has(key))
}

/** Bound on how many keys a message names, so a caller sending a large payload
 *  cannot inflate the analytics error message. Enough keys to recognize the
 *  payload, not enough for a large one to bloat what we record. */
const MAX_KEYS_NAMED = 5

/** Key names only, never values: the message is returned to the caller and
 *  recorded as the analytics error message. */
function namedKeys(keys: readonly string[]): string {
    return keys
        .slice(0, MAX_KEYS_NAMED)
        .map((key) => `"${key}"`)
        .join(', ')
}

/** Bound on the parameter description echoed back with a missing or wrong-type
 *  parameter rejection, so a tool with a long field description cannot inflate
 *  the analytics error message. */
const MAX_PARAM_HINT = 200

/**
 * The parameter's own description, appended to a missing or wrong-type rejection.
 *
 * A bare `missing required parameter: short_id` names the field to fill but not
 * what to fill it with, so a caller that never held the identifier retries the
 * same empty call. The field's description already answers that — where the
 * value comes from and what shape it takes — and this puts it in front of the
 * caller at the moment it needs it, instead of requiring a separate `info` call.
 *
 * Top-level fields only: a nested path describes a field the caller has not
 * reached yet. The text comes from the tool's own schema, never from caller
 * input, so it is safe in the message returned to the caller and recorded as the
 * analytics error message.
 */
function parameterHint(path: ReadonlyArray<PropertyKey>, schema: ZodObjectAny | undefined): string {
    if (!schema || path.length !== 1) {
        return ''
    }
    const root = inputJsonSchema(schema)
    const properties = isRecord(root) ? root['properties'] : undefined
    const field = isRecord(properties) ? properties[String(path[0])] : undefined
    const description = isRecord(field) && typeof field['description'] === 'string' ? field['description'].trim() : ''
    if (!description) {
        return ''
    }
    const capped =
        description.length > MAX_PARAM_HINT ? `${description.slice(0, MAX_PARAM_HINT).trimEnd()}...` : description
    return ` (${capped})`
}

function isRecord(value: unknown): value is Record<string, unknown> {
    return typeof value === 'object' && value !== null && !Array.isArray(value)
}

/** Bounds on how much of a union failure the message unpacks, so one bad array
 *  entry cannot inflate the message or the analytics error string.
 *
 *  Four levels is what the deepest generated query schema needs: a property
 *  filter inside a grouped series sits under the series union, the group's
 *  `nodes` union, the filter union, and the generic filter's own union. A
 *  shallower cap leaves that filter with the bare `Invalid input` this unpacking
 *  exists to remove.
 */
const MAX_UNION_ISSUES_NAMED = 3
const MAX_UNION_VALUES_NAMED = 10
const MAX_UNION_DEPTH = 4

/** The keys a branch rejects because the schema fixes their value, looking
 *  through a branch that is itself a union: a key one inner variant accepts stays
 *  reachable through that branch. */
function rejectedValueKeys(branch: readonly z.core.$ZodIssue[], depth = 0): Set<string> {
    const keys = new Set<string>()
    for (const issue of branch) {
        if (issue.code === 'invalid_value' && issue.path.length === 1) {
            keys.add(String(issue.path[0]))
        } else if (issue.code === 'invalid_union' && issue.path.length === 0 && depth < MAX_UNION_DEPTH) {
            const nested = issue.errors.map((inner) => rejectedValueKeys(inner, depth + 1))
            for (const key of nested[0] ?? []) {
                if (nested.every((set) => set.has(key))) {
                    keys.add(key)
                }
            }
        }
    }
    return keys
}

/** The keys a branch fixes to one value, so `{key: value}` picks it out of the
 *  union. A branch that is itself a union pins what all of its own variants pin —
 *  every variant of a group property filter pins `type` to `group`. */
function pinnedValues(branch: readonly z.core.$ZodIssue[], depth = 0): Map<string, string> {
    const pins = new Map<string, string>()
    for (const issue of branch) {
        if (issue.code === 'invalid_value' && issue.path.length === 1 && issue.values.length === 1) {
            pins.set(String(issue.path[0]), String(issue.values[0]))
        } else if (issue.code === 'invalid_union' && issue.path.length === 0 && depth < MAX_UNION_DEPTH) {
            const nested = issue.errors.map((inner) => pinnedValues(inner, depth + 1))
            for (const [key, value] of nested[0] ?? []) {
                if (nested.every((map) => map.get(key) === value)) {
                    pins.set(key, value)
                }
            }
        }
    }
    return pins
}

/**
 * The key the union switches on, read across the branches: each variant fixes the
 * discriminator to a different value, so one key pinned to several values is the
 * signature of the key that selected between them.
 *
 * Derived across branches rather than taken from one, because a variant can fix a
 * second key to a single value without that key selecting anything: a flag
 * property filter pins `operator` to `flag_evaluates_to`, and a cohort filter pins
 * `key` to `id`. Reading either as the selector drops the variant the caller meant
 * and reports its `type` as the field to rewrite.
 */
function discriminatorKey(branches: readonly (readonly z.core.$ZodIssue[])[]): string | undefined {
    const pinned = new Map<string, Set<string>>()
    for (const branch of branches) {
        for (const [key, value] of pinnedValues(branch)) {
            const values = pinned.get(key) ?? new Set<string>()
            values.add(value)
            pinned.set(key, values)
        }
    }
    let selector: string | undefined
    let widest = 1
    for (const [key, values] of pinned) {
        if (values.size > widest) {
            selector = key
            widest = values.size
        }
    }
    return selector
}

/**
 * The union branch that best matches the input: the variant the caller named, or
 * failing that the one that raised the fewest complaints.
 *
 * A series entry keyed `kind: "ActionsNode"` and missing `name` fails every
 * branch with one complaint each, so the shortest list alone would pick
 * `EventsNode` and advise rewriting the `kind` the caller meant.
 */
function bestUnionBranch(branches: readonly (readonly z.core.$ZodIssue[])[]): readonly z.core.$ZodIssue[] | undefined {
    const populated = branches.filter((branch) => branch.length > 0)
    const selector = discriminatorKey(populated)
    // Once the selector is known, the caller's own value for it picks the
    // variant. Where no key selects anything, keep the variants that pin nothing
    // the caller contradicted, so a `breakdowns` entry still hears the whole type
    // list its generic variant takes rather than the one its group variant pins.
    const named =
        selector === undefined
            ? populated.filter((branch) => pinnedValues(branch).size === 0)
            : populated.filter((branch) => !rejectedValueKeys(branch).has(selector))
    const candidates = named.length > 0 ? named : populated
    // A nullable field — `union([array(metric), null])` on the experiment metrics
    // — rejects a malformed array with the null branch's single complaint,
    // "expected null, received array", as the shortest list, burying the real
    // error inside the array branch. A branch with an issue below the root
    // engaged with the value's contents, so when one exists, a branch that only
    // rejects the whole value's type restates what the caller already knows.
    const engaged = candidates.filter((branch) => !rejectsWholeValueType(branch))
    let best: readonly z.core.$ZodIssue[] | undefined
    for (const branch of engaged.length > 0 ? engaged : candidates) {
        if (best === undefined || branch.length < best.length) {
            best = branch
        }
    }
    return best
}

/** True when the branch's every issue says the whole value is the wrong type,
 *  with nothing about its contents — the shape of a `null` branch rejecting an
 *  array, or a scalar branch rejecting an object. */
function rejectsWholeValueType(branch: readonly z.core.$ZodIssue[]): boolean {
    return branch.every((issue) => issue.code === 'invalid_type' && issue.path.length === 0)
}

/** The accepted values, when every branch of a union rejects the same enum
 *  value because the options are split across several enums. */
function unionValueOptions(branches: readonly (readonly z.core.$ZodIssue[])[]): string[] | undefined {
    const values: string[] = []
    for (const branch of branches) {
        const issue = branch.length === 1 ? branch[0] : undefined
        if (!issue || issue.code !== 'invalid_value' || issue.path.length > 0) {
            return undefined
        }
        for (const value of issue.values) {
            values.push(String(value))
        }
    }
    return values.length > 0 ? [...new Set(values)] : undefined
}

/**
 * Unpacks a union rejection into the field that actually failed.
 *
 * Zod reports a union miss as one `Invalid input` at the union itself, so a
 * malformed series entry arrives as `parameter "series.0": Invalid input`, which
 * names the entry but never the key to change. Descending into the
 * closest-matching branch names the offending field instead.
 *
 * Reports field names and schema-declared values only, never caller input.
 */
function describeUnionIssue(
    branches: readonly (readonly z.core.$ZodIssue[])[],
    path: ReadonlyArray<PropertyKey>,
    depth = 0
): string | undefined {
    if (depth >= MAX_UNION_DEPTH) {
        return undefined
    }
    const name = path.map(String).join('.')
    const options = unionValueOptions(branches)
    if (options) {
        const shown = options.slice(0, MAX_UNION_VALUES_NAMED).join(', ')
        const rest = options.length > MAX_UNION_VALUES_NAMED ? `, ... (${options.length} accepted values)` : ''
        return `parameter "${name}" must be one of: ${shown}${rest}`
    }
    const branch = bestUnionBranch(branches)
    if (!branch) {
        return undefined
    }
    const parts = branch.slice(0, MAX_UNION_ISSUES_NAMED).map((issue) => {
        const nestedPath = [...path, ...issue.path]
        if (issue.code === 'invalid_union') {
            const nested = describeUnionIssue(issue.errors, nestedPath, depth + 1)
            if (nested) {
                return nested
            }
        }
        const nestedName = nestedPath.map(String).join('.')
        return nestedName ? `parameter "${nestedName}": ${issue.message}` : issue.message
    })
    if (branch.length > MAX_UNION_ISSUES_NAMED) {
        parts.push('...')
    }
    return [...new Set(parts)].join('; ')
}

/** Turns a Zod validation failure into a short, field-named message the model
 *  can act on. Without it, a missing/`undefined` path segment slips through to
 *  the HTTP layer and the API returns a generic 404 that reads as "entity does
 *  not exist" — steering recovery toward re-checking the ID rather than the
 *  malformed parameter.
 *
 *  Callers must `safeParse(input, { reportInput: true })` so `issue.input`
 *  distinguishes a missing required field from a present-but-wrong one (the
 *  key is absent without the option, and the check degrades to the wrong-type
 *  message). `reportInput` embeds raw input values in the ZodError, including
 *  its `.message` — keep the error local; never log or capture it. */
export function formatInputValidationError(
    toolName: string,
    error: z.ZodError,
    input?: unknown,
    schema?: ZodObjectAny
): string {
    // A strict schema rejects unknown keys instead of dropping them, and the
    // `unrecognized_keys` branch below already names them.
    const keysWereRejected = error.issues.some((issue) => issue.code === 'unrecognized_keys')
    // Resolved once, and on first need: the answer reads only `input` and
    // `schema`, so it is the same for every issue, while it costs a schema parse
    // per stray object key. Most rejections never reach the branch that asks.
    //
    // Top-level misses only, like its sibling: wrapping the payload can leave a
    // whole parameter unfilled, but never a field inside one the caller reached.
    let wrapper: { key: string | undefined } | undefined
    const overWrappedKey = (issuePath: ReadonlyArray<PropertyKey>): string | undefined => {
        if (issuePath.length !== 1) {
            return undefined
        }
        wrapper ??= { key: overWrappedPayloadKey(input, schema) }
        return wrapper.key
    }
    const parts = error.issues.map((issue) => {
        const path = issue.path.map(String).join('.')
        if (issue.code === 'invalid_type') {
            if ('input' in issue && issue.input === undefined) {
                const hint = parameterHint(issue.path, schema)
                if (looksLikeUnwrappedPayload(issue.path, input, schema)) {
                    const { shape, unplaced } = acceptedWrapperShape(path, input, schema)
                    const rejected = unplaced.length
                        ? `; these keys are not fields of ${path}, so remove or rename them: ${namedKeys(unplaced)}`
                        : ''
                    return `missing required parameter: ${path}${hint}; the fields you sent belong inside it, so resend them as ${shape}${rejected}`
                }
                const overWrapped = overWrappedKey(issue.path)
                if (overWrapped !== undefined) {
                    const shape = acceptedTopLevelShape((input as Record<string, unknown>)[overWrapped], schema)
                    return `missing required parameter: ${path}${hint}; this tool takes these fields at the top level, not nested under "${overWrapped}", so resend them as ${shape}`
                }
                const dropped = keysWereRejected ? [] : undeclaredKeys(input, schema)
                if (dropped.length) {
                    return `missing required parameter: ${path}${hint}; this tool ignored these keys it does not accept: ${namedKeys(dropped)}`
                }
                return `missing required parameter: ${path}${hint}`
            }
            // The type alone does not say which values the field accepts, for
            // example a bucket count where the caller sent a unit such as "day".
            return `parameter "${path}" must be of type ${issue.expected}${parameterHint(issue.path, schema)}`
        }
        if (issue.code === 'invalid_union') {
            const expanded = describeUnionIssue(issue.errors, issue.path)
            if (expanded) {
                return expanded
            }
        }
        if (issue.code === 'unrecognized_keys') {
            return `unexpected ${issue.keys.length > 1 ? 'properties' : 'property'}: ${issue.keys.join(', ')}`
        }
        // A too-long string names the limit and the input's actual length so the
        // agent knows how much to trim (zod's default names only the limit).
        // Surfaces the LENGTH only, never the value: the message is returned to
        // the caller and recorded as the analytics error_message. `issue.input`
        // is only present under `reportInput: true`; without it, or for
        // non-string origins, fall through to zod's limit-naming default.
        if (issue.code === 'too_big' && issue.origin === 'string' && typeof issue.input === 'string') {
            return `parameter "${path}" is too long: ${issue.input.length} characters (max ${issue.maximum})`
        }
        return path ? `parameter "${path}": ${issue.message}` : issue.message
    })
    return `Invalid input for "${toolName}": ${[...new Set(parts)].join('; ')}`
}

/** Caps on what we record so a single failure can't blow up analytics cardinality. */
const MAX_VALIDATION_DESCRIPTORS = 20
const MAX_KEY_LENGTH = 64

/**
 * Issue codes where the type of the rejected value is the diagnostic signal: a
 * parameter that is absent and one that is present under the right name but the
 * wrong shape are different bugs with different fixes, and both otherwise read as
 * a bare `invalid_type`.
 */
const TYPE_REVEALING_CODES = new Set(['invalid_type', 'invalid_union'])

/**
 * Recorded in place of a path segment the schema never declared. An open record
 * (`generate-app-url`'s `params: z.record(z.string(), z.string())`) puts the
 * caller's own key in the issue path, so recording the path verbatim would carry
 * caller text into analytics. Which field held the bad value is preserved; only
 * the key inside it is masked.
 */
const UNDECLARED_PATH_SEGMENT = '*'

/** Defensive bound on the JSON Schema walk behind `declaredPropertyNames`. */
const MAX_SCHEMA_WALK_DEPTH = 20

/**
 * Joins an issue path into a descriptor, collapsing array indices to `N` and
 * masking any segment `declaredNames` doesn't cover.
 *
 * `series.0.event` and `series.1.event` describe one defect. Without the collapse
 * a malformed 50-element array yields 50 distinct descriptors that fill
 * `MAX_VALIDATION_DESCRIPTORS` with restatements of itself — and because the cap
 * truncates in schema-traversal order, it evicts genuinely different fields that
 * failed later. The dedupe is what keeps the cap meaningful.
 *
 * `declaredNames` is omitted only where every segment is ours by construction
 * (`describeApiValidationError`, whose `attr` is a serializer field name).
 */
function normalizeDescriptorPath(segments: readonly PropertyKey[], declaredNames?: ReadonlySet<string>): string {
    if (!segments.length) {
        return '(root)'
    }
    return segments
        .map((segment) => {
            if (typeof segment === 'number' || /^\d+$/.test(String(segment))) {
                return 'N'
            }
            const name = String(segment)
            if (declaredNames && !declaredNames.has(name)) {
                return UNDECLARED_PATH_SEGMENT
            }
            return name
        })
        .join('.')
        .slice(0, MAX_KEY_LENGTH)
}

const declaredPropertyNamesCache = new WeakMap<object, ReadonlySet<string>>()
const inputJsonSchemaCache = new WeakMap<object, unknown>()

/**
 * The agent-facing JSON Schema for a tool, converted once per schema object.
 *
 * A schema that can't be converted caches `null`, so a failure costs detail once
 * rather than being retried on every rejection.
 */
function inputJsonSchema(schema: z.ZodType): unknown {
    if (inputJsonSchemaCache.has(schema)) {
        return inputJsonSchemaCache.get(schema)
    }
    let converted: unknown = null
    try {
        converted = z.toJSONSchema(schema, { io: 'input' })
    } catch {
        // Neither telemetry nor an error message may break a tool call.
    }
    inputJsonSchemaCache.set(schema, converted)
    return converted
}

/**
 * Every property name a tool's schema declares, at any depth. A path segment
 * outside this set came from an open record or a catchall, which means the caller
 * chose it.
 *
 * Read off the JSON Schema exec already generates for `info`, so this depends on
 * no Zod internals. A schema that can't be converted yields an empty set: more
 * masking than strictly needed, never less.
 */
function declaredPropertyNames(schema: z.ZodType): ReadonlySet<string> {
    const cached = declaredPropertyNamesCache.get(schema)
    if (cached) {
        return cached
    }
    const names = new Set<string>()
    collectDeclaredPropertyNames(inputJsonSchema(schema), names)
    declaredPropertyNamesCache.set(schema, names)
    return names
}

function collectDeclaredPropertyNames(node: unknown, into: Set<string>, depth = 0): void {
    if (depth > MAX_SCHEMA_WALK_DEPTH || typeof node !== 'object' || node === null) {
        return
    }
    if (Array.isArray(node)) {
        for (const child of node) {
            collectDeclaredPropertyNames(child, into, depth + 1)
        }
        return
    }
    for (const [key, value] of Object.entries(node)) {
        // Only a `properties` map is keyed by field names. `patternProperties`,
        // `additionalProperties` and `$defs` are keyed by pattern or definition name,
        // so descend into their values without recording the keys.
        if (key === 'properties' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
            for (const [name, child] of Object.entries(value)) {
                into.add(name)
                collectDeclaredPropertyNames(child, into, depth + 1)
            }
            continue
        }
        collectDeclaredPropertyNames(value, into, depth + 1)
    }
}

/** The JSON-shaped type of a rejected value — never the value, never its length. */
function describeReceivedType(value: unknown): string {
    if (value === null) {
        return 'null'
    }
    if (Array.isArray(value)) {
        return 'array'
    }
    return typeof value
}

/**
 * Builds a descriptor in the same `path:code[:received]` shape
 * `describeValidationError` emits, for a rejection that came from the PostHog API
 * rather than the local schema — so both kinds of validation failure answer one
 * query instead of requiring `$mcp_error_message` to be string-parsed.
 *
 * `attr` is one of our own serializer field names and `code` a DRF code; neither
 * carries caller input, unlike the API's free-text `detail`.
 */
export function describeApiValidationError(attr: string | undefined, code: string | undefined): string[] {
    const path = normalizeDescriptorPath((attr ?? '').split('.').filter(Boolean))
    return [`${path}:${code ?? 'unknown'}`]
}

/**
 * Derives a value-free descriptor of a validation failure for telemetry, so a
 * contract regression (agents sending a field name the schema doesn't accept) is
 * diagnosable from the `$mcp_tool_call` event alone — without ever recording the
 * request payload.
 *
 * `fields` are the offending field path + issue code, plus the received type where
 * that distinguishes the bug (e.g. `id:invalid_type:undefined` for an omitted
 * parameter vs `query:invalid_union:string` for an envelope the agent flattened).
 * Records only structural information: field names, issue codes, and the TYPE of a
 * rejected value. It never records input VALUES — the ZodError embeds those in
 * `issue.input` and in `.message` (see `formatInputValidationError`), so this reads
 * `typeof issue.input` and never the value behind it. `schema` is what keeps that
 * true of the field paths as well: a key the schema never declared belongs to the
 * caller, so it is masked rather than recorded (see `normalizeDescriptorPath`).
 */
export function describeValidationError(error: z.ZodError, schema: z.ZodType): { fields: string[] } {
    const declaredNames = declaredPropertyNames(schema)
    const fields = [
        ...new Set(
            error.issues.map((issue) => {
                const descriptor = `${normalizeDescriptorPath(issue.path, declaredNames)}:${issue.code}`
                // `input` is only present under `safeParse(..., { reportInput: true })`;
                // without it there is no type to report, and an absent value and an
                // unreported one must not both read as `undefined`.
                if (!TYPE_REVEALING_CODES.has(issue.code) || !('input' in issue)) {
                    return descriptor
                }
                return `${descriptor}:${describeReceivedType(issue.input)}`
            })
        ),
    ].slice(0, MAX_VALIDATION_DESCRIPTORS)
    return { fields }
}

const PARAMETER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
const DIGIT_RUN_PATTERN = /\d{5}/
const POSTHOG_TOKEN_PREFIX_PATTERN = /^ph[a-z]_/
const CREDENTIAL_SEGMENT_MIN_LENGTH = 16

function hasCredentialSegment(key: string): boolean {
    return key.split('_').some((segment) => segment.length >= CREDENTIAL_SEGMENT_MIN_LENGTH && /\d/.test(segment))
}

/**
 * Undeclared names come from the caller and can hold private data, so only parameter-shaped
 * ones are recorded. The digit checks keep out phone numbers, IDs, and most tokens. The prefix
 * check keeps out PostHog tokens, whose suffix can have no digits.
 */
const shouldRecordInputKey: ShouldRecordInputKeyFn = (key, { declared }) =>
    declared ||
    (PARAMETER_NAME_PATTERN.test(key) &&
        !DIGIT_RUN_PATTERN.test(key) &&
        !hasCredentialSegment(key) &&
        !POSTHOG_TOKEN_PREFIX_PATTERN.test(key))

/**
 * `$mcp_input_keys` and `$mcp_input_aliases_used` for one call, from the SDK helper, with no
 * values. The alias map comes from the schema's own `normalizeParamAliases` layers, so
 * alias names count as declared and each alias the normaliser relied on is recorded as
 * `alias:canonical`. The SDK owns the limits (20 names, 64 characters), declared-names-first
 * ordering, and dropping its injected `context`, `llm_model`, and `conversation_id` unless the
 * schema declares them. `shouldRecordInputKey` decides which undeclared names are recorded.
 */
export function describeInputShape(input: unknown, schema?: z.ZodType): Record<string, unknown> {
    return getToolInputProperties(input, schema, {
        shouldRecordInputKey,
        inputAliases: schema ? readParamAliases(schema) : undefined,
    })
}

/** Whether the tool's input schema declares an `output_format` field. Unwraps
 *  `z.preprocess(...)` pipes (e.g. the id-alias normalization on insight-query)
 *  to reach the underlying object schema. */
function schemaHasOutputFormat(schema: ZodObjectAny): boolean {
    let current: z.ZodType = schema
    while (current instanceof z.ZodPipe) {
        current = current.out as z.ZodType
    }
    return current instanceof z.ZodObject && 'output_format' in current.shape
}

/**
 * Exec mode owns output encoding through the `--json` call flag, so tools must
 * not also advertise their `output_format` input — an agent passing
 * `output_format: "json"` would make the handler skip the server-side formatter
 * only for exec to TOON-encode the raw result anyway. `call` folds the flag back
 * into the field for tools that have it (see the `call` verb), so hiding it here
 * loses no capability.
 */
function stripOutputFormatProperty(jsonSchema: Record<string, unknown>): Record<string, unknown> {
    const properties = jsonSchema.properties as Record<string, unknown> | undefined
    if (!properties || !('output_format' in properties)) {
        return jsonSchema
    }
    const { output_format: _omitted, ...rest } = properties
    return { ...jsonSchema, properties: rest }
}

/** A lowercase hyphenated token, the shape every name in the tool catalog takes. */
const HINT_TOOL_NAME_PATTERN = /[a-z][a-z0-9]*(?:-[a-z0-9]+)+/g

/**
 * Whether every tool the hint names is one this connection can call. A hint is
 * free text, so it can name a tool that is behind its own gate here — the second
 * dead end the successor filter exists to prevent. A hyphenated word the catalog
 * has no tool for is prose, so it never suppresses the hint.
 */
function hintNamesOnlyAvailableTools(hint: string, available: Set<string>): boolean {
    const definitions = getToolDefinitions()
    return (hint.match(HINT_TOOL_NAME_PATTERN) ?? []).every(
        (token) => definitions[token] === undefined || available.has(token)
    )
}

/**
 * Message for a tool a feature flag removed from this connection's catalog.
 * Names only the successors the catalog can actually serve, because a successor
 * behind its own gate is no more callable than the tool it replaced. The hint is
 * held to the same rule. Never names the flag — the agent cannot act on a flag
 * key, and the key is internal.
 */
function flagGatedToolMessage(gated: FlagGatedTool, tools: Tool<ZodObjectAny>[]): string {
    const available = new Set(tools.map((t) => t.name))
    const reachable = gated.supersededBy.filter((successor) => available.has(successor))
    const hint =
        gated.redirectHint && hintNamesOnlyAvailableTools(gated.redirectHint, available) ? ` ${gated.redirectHint}` : ''
    if (reachable.length === 0) {
        return `Tool "${gated.name}" exists, but it is not enabled on this PostHog connection. The capability was not removed. Run "search ${gated.name}" to find an enabled tool for the same job.${hint}`
    }
    const successors = reachable.map((successor) => `"${successor}"`).join(' or ')
    return `Tool "${gated.name}" is retired on this PostHog connection. Use ${successors} instead.${hint}`
}

function missingScopeRecovery(context: Context | undefined, oauthClientId: string | undefined): string {
    if (isChatGptAppConnection(oauthClientId)) {
        return 'The PostHog app in ChatGPT and Codex does not request every PostHog scope, so reconnecting it adds these scopes only if the app asks for them. If the user already reconnected and approved all access, this tool is not available through the app yet. Continue with the other tools.'
    }
    switch (classifyAuthMethod(context?.api.config.apiToken)) {
        case 'oauth':
            return 'Reauthorize the PostHog MCP connection and approve these scopes.'
        case 'personal_api_key':
            return `Add these scopes to the personal API key. The change reaches this connection within ${API_KEY_CACHE_TTL_MS / 60_000} minutes, and reconnecting the client does not make it faster.`
        default:
            return 'Reauthorize the PostHog MCP connection, or add these scopes to the personal API key.'
    }
}

export function missingToolScopeError(
    tool: ScopeGatedTool,
    context: Context | undefined,
    oauthClientId: string | undefined
): ExecCommandError {
    return new ExecCommandError(
        `Tool "${tool.name}" exists, but this MCP connection is missing the required scope(s): ${tool.missingScopes.join(', ')}. ${missingScopeRecovery(context, oauthClientId)} Logging in to PostHog in a browser does not update MCP permissions.`,
        'missing_scope'
    )
}

function findTool(
    tools: Tool<ZodObjectAny>[],
    scopeGatedTools: ScopeGatedTool[],
    flagGatedTools: FlagGatedTool[],
    name: string,
    context: Context | undefined,
    isNotGranted: (name: string) => boolean,
    oauthClientId: string | undefined
): Tool<ZodObjectAny> {
    const tool = tools.find((t) => t.name === name)
    if (!tool) {
        const redirect = getDeprecatedToolRedirect(name, tools)
        if (redirect) {
            throw new ExecCommandError(redirect, 'deprecated_tool')
        }
        const flagGatedTool = flagGatedTools.find((candidate) => candidate.name === name)
        if (flagGatedTool) {
            throw new ExecCommandError(flagGatedToolMessage(flagGatedTool, tools), 'gated_tool')
        }
        const scopeGatedTool = scopeGatedTools.find((candidate) => candidate.name === name)
        if (scopeGatedTool) {
            throw missingToolScopeError(scopeGatedTool, context, oauthClientId)
        }
        if (isNotGranted(name)) {
            throw new ExecCommandError(
                `Tool "${name}" exists, but the owner of this run did not grant it. This refusal is final. Do not retry it, and do not reach the same data or action another way.`,
                'tool_not_granted'
            )
        }
        throw new ExecCommandError(
            `Unknown tool: "${name}". Run "search ${name}" to find the current tool name before claiming the capability is unavailable.`,
            'unknown_tool'
        )
    }
    return tool
}

export function createExecTool(
    allTools: Tool<ZodObjectAny>[],
    context: Context | undefined,
    toolDescription: string,
    commandReference: string,
    mcpConsumer: string | undefined,
    trackInnerCall?: ExecInnerCallTracker,
    scopeGatedTools: ScopeGatedTool[] = [],
    options: ExecToolOptions = {}
): Tool<ExecSchema> {
    const ExecSchema = makeExecSchema(commandReference)
    const flagGatedTools = options.flagGatedTools ?? []

    return {
        name: 'exec',
        title: 'PostHog analytics, dashboards, insights, feature flags & more',
        description: toolDescription,
        schema: ExecSchema,
        scopes: [],
        annotations: { ...EXEC_TOOL_ANNOTATIONS },
        handler: async (_context: Context, params: z.infer<ExecSchema>) => {
            const { verb, rest } = parseCommand(params.command)
            // Reported up front so a command that throws (unknown tool, bad regex) still
            // records what was attempted — those are the failures worth counting.
            options.trackCommand?.({ exec_verb: verb })

            // Without this the trailing commands ride along as part of the first one's
            // argument and come back as an unknown tool name, which explains nothing.
            const batched = splitBatchedCommands(params.command)
            if (batched) {
                throw new ExecCommandError(batchedCommandMessage(batched), 'batched_command')
            }

            let gatewayTools: Tool<ZodObjectAny>[] | undefined
            const withheldGatewayToolNames = new Set<string>()
            /** PostHog's tools plus any third-party tools the caller has connected.
             *  Resolved at most once per command, and only for commands that need a
             *  roster — `learn` never touches the gateway. */
            const resolveTools = async (): Promise<Tool<ZodObjectAny>[]> => {
                if (!options.gatewayToolsProvider) {
                    return allTools
                }
                if (gatewayTools === undefined) {
                    gatewayTools = await options.gatewayToolsProvider()
                    const filter = options.gatewayToolFilter
                    gatewayTools = gatewayTools.filter(
                        (tool) =>
                            !filter?.excludeTools?.includes(tool.name) &&
                            (!(filter?.tools?.length || filter?.features?.length) || filter?.tools?.includes(tool.name))
                    )
                    const { heldTools } = options
                    if (heldTools) {
                        for (const tool of gatewayTools) {
                            if (!heldTools.has(tool.name)) {
                                withheldGatewayToolNames.add(tool.name)
                            }
                        }
                        gatewayTools = gatewayTools.filter((tool) => heldTools.has(tool.name))
                    }
                }
                return gatewayTools.length > 0 ? [...allTools, ...gatewayTools] : allTools
            }
            // Only a name that exists is refused as not granted, so a typo still sends the agent to `search`.
            const isNotGranted = (name: string): boolean =>
                options.heldTools !== undefined &&
                !options.heldTools.has(name) &&
                (getToolDefinitions()[name] !== undefined || withheldGatewayToolNames.has(name))

            switch (verb) {
                case 'help':
                    return execHelp(rest, options.learnCatalog !== undefined)

                case 'learn': {
                    // Before the availability check, so a rejected skill command still records its form.
                    options.trackCommand?.({ exec_verb: verb, ...classifyLearnCommand(rest) })
                    const learnCatalog = options.learnCatalog
                    if (!learnCatalog) {
                        // `learn` is only advertised when a catalog exists, so without one
                        // it's an unsupported verb rather than a misuse of a real command.
                        throw new ExecCommandError(
                            'The learn command is not available for this client.',
                            'unknown_command'
                        )
                    }
                    let learnResult: string
                    try {
                        learnResult = await learnCatalog.execute(rest)
                    } catch (error) {
                        throw classifyLearnError(error)
                    }
                    return learnResult
                }

                case 'tools': {
                    const names = allTools.map((t) => t.name)
                    const connected = await resolveConnectedSummary(resolveTools, allTools.length)
                    if (!connected) {
                        return JSON.stringify(names)
                    }
                    // Summarize rather than list: a user with several connected servers can
                    // have hundreds of third-party tools, and dumping them all here would
                    // cost more context than `search` ever does.
                    return JSON.stringify({ tools: names, connected_servers: connected })
                }

                case 'search': {
                    if (!rest) {
                        throw new ExecCommandError('Usage: search <words or regex_pattern>', 'usage')
                    }
                    // Bound the user-supplied pattern length to limit the blast
                    // radius of a pathological (catastrophic-backtracking) regex.
                    if (rest.length > MAX_SEARCH_PATTERN_LENGTH) {
                        throw new ExecCommandError(
                            `Search pattern too long (${rest.length} chars, max ${MAX_SEARCH_PATTERN_LENGTH}). Use a shorter, more targeted pattern.`,
                            'usage'
                        )
                    }

                    // Agents quote single words (`search "project"`), and a literal quote
                    // matches no tool.
                    const query = rest.replace(/["'`]/g, '').trim()
                    if (!query) {
                        throw new ExecCommandError('Usage: search <words or regex_pattern>', 'usage')
                    }
                    // Route by pattern shape: a pattern with regex metacharacters
                    // (e.g. `query-`, `feature-flag`) keeps the original regex
                    // predicate; plain words — including multi-word, natural-
                    // language queries — use forgiving token ranking.
                    const searchableTools = await resolveTools()
                    // `matches` is the page the agent sees; `matchedNames` is every match,
                    // which is what the counts report — a truncated page would make a broad
                    // query look as narrow as a precise one.
                    let matchedNames: string[] = []
                    let matches: string[] = []
                    let gatedMatches: ScopeGatedTool[] = []
                    let truncatedFrom = 0
                    let fallbackFrom: string | undefined
                    // The word fallback searches something other than what the agent typed, so
                    // the catalog hint has to read the matches against the term that found them.
                    let searchTerm = query
                    const rankByWords = (words: string): void => {
                        searchTerm = words
                        const ranked = searchToolsRanked(searchableTools, words)
                        truncatedFrom = ranked.length > MAX_RANKED_SEARCH_RESULTS ? ranked.length : 0
                        matchedNames = ranked.map((r) => r.name)
                        matches = matchedNames.slice(0, MAX_RANKED_SEARCH_RESULTS)
                        // Preserve ranked order for gated matches too, then map
                        // each name back to its ScopeGatedTool (for missingScopes).
                        const gatedByName = new Map(scopeGatedTools.map((t) => [t.name, t]))
                        gatedMatches = searchToolsRanked(scopeGatedTools, words)
                            .map((r) => gatedByName.get(r.name))
                            .filter((t): t is ScopeGatedTool => t !== undefined)
                    }
                    if (isRegexPattern(query)) {
                        try {
                            matchedNames = searchToolsRegex(searchableTools, query).map((t) => t.name)
                            matches = matchedNames
                            gatedMatches = searchToolsRegex(scopeGatedTools, query)
                        } catch {
                            throw new ExecCommandError(`Invalid regex pattern: "${query}"`, 'invalid_regex')
                        }
                        // A guessed name such as `project-update` matches nothing as a regex,
                        // but its words usually name the tool the agent wants.
                        const words = query.replace(/[^a-z0-9]+/gi, ' ').trim()
                        if (matchedNames.length === 0 && gatedMatches.length === 0 && words) {
                            rankByWords(words)
                            if (matchedNames.length > 0 || gatedMatches.length > 0) {
                                fallbackFrom = query
                            }
                        }
                    } else {
                        rankByWords(query)
                    }

                    options.trackCommand?.({
                        exec_verb: verb,
                        exec_search_query: rest,
                        exec_search_match_count: fallbackFrom === undefined ? matchedNames.length : 0,
                        ...(fallbackFrom === undefined
                            ? {}
                            : { exec_search_fallback_match_count: matchedNames.length }),
                        exec_search_gateway_match_count: matchedNames.filter(isGatewayToolName).length,
                    })

                    if (gatedMatches.length > 0) {
                        const requiredScopes = [...new Set(gatedMatches.flatMap((t) => t.missingScopes))].sort()
                        return JSON.stringify({
                            matches,
                            scope_gated_matches: gatedMatches.map((t) => ({
                                name: t.name,
                                missing_scopes: t.missingScopes,
                            })),
                            hint:
                                `These tools also match but are hidden because the API key is missing the ` +
                                `required scope(s): ${requiredScopes.join(', ')}. ${missingScopeRecovery(context, options.oauthClientId)}`,
                        })
                    }
                    if (matches.length === 0) {
                        return JSON.stringify({
                            matches: [],
                            hint: `No tools matched "${query}". Search again with plain words that describe the task, for example "create dashboard". Run "tools" only if that also finds nothing.`,
                        })
                    }
                    const fallbackHint =
                        fallbackFrom === undefined
                            ? undefined
                            : `No tool is named "${fallbackFrom}". These are the closest matches by its words.`
                    if (truncatedFrom > 0) {
                        const catalogHint = catalogDiscoveryHint(
                            allTools,
                            namesMatchingSearch(matchedNames, searchTerm)
                        )
                        return JSON.stringify({
                            matches,
                            truncated: true,
                            hint: [
                                fallbackHint,
                                catalogHint,
                                `Showing the top ${MAX_RANKED_SEARCH_RESULTS} of ${truncatedFrom} matches, ranked by relevance. Use a more specific query to narrow the results.`,
                            ]
                                .filter(Boolean)
                                .join(' '),
                        })
                    }
                    const catalogHint = catalogDiscoveryHint(allTools, namesMatchingSearch(matchedNames, searchTerm))
                    const hint = [fallbackHint, catalogHint].filter(Boolean).join(' ')
                    if (hint) {
                        return JSON.stringify({ matches, hint })
                    }
                    return JSON.stringify(matches)
                }

                case 'info': {
                    if (!rest) {
                        throw new ExecCommandError('Usage: info [--json] <tool_name>', 'usage')
                    }
                    const forceJson = rest.startsWith('--json ') || rest === '--json'
                    const infoArgs = forceJson ? rest.slice('--json'.length).trim() : rest
                    if (!infoArgs) {
                        throw new ExecCommandError('Usage: info [--json] <tool_name>', 'usage')
                    }
                    const tool = findTool(
                        await resolveTools(),
                        scopeGatedTools,
                        flagGatedTools,
                        infoArgs,
                        context,
                        isNotGranted,
                        options.oauthClientId
                    )
                    // `io: 'input'` mirrors the advertised `tools/list` schema and the executor's
                    // validation: fields with a Zod `.default()` (e.g. a query `kind` discriminator)
                    // are optional and auto-filled. The default `io: 'output'` would list them as
                    // required, misrepresenting them as mandatory input the caller must supply.
                    const fullSchema =
                        tool.rawInputSchema ??
                        stripOutputFormatProperty(
                            z.toJSONSchema(tool.schema, { io: 'input' }) as Record<string, unknown>
                        )
                    // YAML for the top shape, but inputSchema stays as a JSON
                    // string dumped inside the YAML — JSON Schema is conventionally
                    // JSON and converting it to YAML obscures `$ref`, `oneOf`, etc.
                    const serialize = (payload: Record<string, unknown>, schema: unknown): string => {
                        if (forceJson) {
                            return JSON.stringify({ ...payload, inputSchema: schema })
                        }
                        return stringifyYaml({ ...payload, inputSchema: JSON.stringify(schema) }, { lineWidth: 0 })
                    }

                    const topShape = {
                        name: tool.name,
                        title: tool.title,
                        description: tool.description,
                        annotations: tool.annotations,
                    }
                    const fullOutput = serialize(topShape, fullSchema)

                    if (fullOutput.length <= TOKEN_CHAR_LIMIT) {
                        return fullOutput
                    }

                    // Schema too large — return summary with drill-down hints.
                    // Each complex field's `hint` carries the imperative to run
                    // `schema` before populating it, so no separate directive is
                    // needed here.
                    const summary = summarizeSchema(fullSchema as Record<string, unknown>, tool.name)
                    return serialize(topShape, summary)
                }

                case 'schema': {
                    if (!rest) {
                        throw new ExecCommandError('Usage: schema <tool_name> [field_path]', 'usage')
                    }
                    const { verb: schemaToolName, rest: fieldPath } = parseCommand(rest)
                    const schemaTool = findTool(
                        await resolveTools(),
                        scopeGatedTools,
                        flagGatedTools,
                        schemaToolName,
                        context,
                        isNotGranted,
                        options.oauthClientId
                    )
                    // See the `info` command: `io: 'input'` keeps this in sync with the advertised
                    // schema and validation, so `.default()` fields aren't shown as required.
                    const fullJsonSchema =
                        schemaTool.rawInputSchema ??
                        stripOutputFormatProperty(
                            z.toJSONSchema(schemaTool.schema, { io: 'input' }) as Record<string, unknown>
                        )

                    if (!fieldPath) {
                        // The bare `schema <tool>` view is always a summary. Any
                        // field that still needs drilling carries the imperative
                        // in its own `hint`, so the summary stands on its own.
                        return JSON.stringify(summarizeSchema(fullJsonSchema, schemaToolName))
                    }

                    const resolved = resolveSchemaPath(fullJsonSchema, fieldPath)
                    if (!resolved) {
                        const available = listAvailablePaths(fullJsonSchema)
                        throw new ExecCommandError(
                            `Unknown path "${fieldPath}". Available: ${available.join(', ')}`,
                            'usage'
                        )
                    }

                    const serialized = JSON.stringify({
                        field: fieldPath,
                        schema: resolved,
                    })
                    if (serialized.length <= TOKEN_CHAR_LIMIT) {
                        return serialized
                    }

                    // Field schema too large — return a summary instead. The
                    // summary's complex sub-fields carry the drill-down `hint`,
                    // so the response shape stays the same as the inline case
                    // (`{ field, schema }`) — no separate top-level note.
                    return JSON.stringify({
                        field: fieldPath,
                        schema: summarizeSchema(resolved as Record<string, unknown>, schemaToolName, fieldPath),
                    })
                }

                case 'call': {
                    if (!rest) {
                        throw new ExecCommandError(CALL_USAGE, 'usage')
                    }
                    if (!context) {
                        // Deliberately untyped: a wiring fault, not an agent mistake, so it
                        // belongs in the `internal` bucket its siblings are kept out of.
                        throw new Error('Cannot call PostHog tools without an API context')
                    }
                    const leadingFlags = parseCallFlags(rest)
                    if (!leadingFlags.rest) {
                        throw new ExecCommandError(CALL_USAGE, 'usage')
                    }
                    const { verb: toolName, rest: afterToolName } = parseCommand(leadingFlags.rest)
                    const bodyFlags = parseCallBodyFlags(afterToolName)
                    const forceJson = leadingFlags.forceJson || bodyFlags.forceJson
                    const confirmed = leadingFlags.confirmed || bodyFlags.confirmed
                    const jsonBody = bodyFlags.rest
                    const tool = findTool(
                        await resolveTools(),
                        scopeGatedTools,
                        flagGatedTools,
                        toolName,
                        context,
                        isNotGranted,
                        options.oauthClientId
                    )
                    if (options.requireDestructiveConfirmation && tool.annotations.destructiveHint && !confirmed) {
                        throw new ExecCommandError(
                            `Tool "${tool.name}" is destructive. Re-run with "call --confirm ${tool.name} ..." after verifying the target IDs. Use "info ${tool.name}" to inspect the tool first.`,
                            'needs_confirmation'
                        )
                    }
                    let input: Record<string, unknown>
                    if (!jsonBody) {
                        input = {}
                    } else {
                        try {
                            input = JSON.parse(jsonBody) as Record<string, unknown>
                        } catch (err) {
                            const detail = err instanceof Error ? err.message : String(err)
                            throw new ExecCommandError(`Invalid JSON input: ${detail}`, 'invalid_json')
                        }
                    }

                    // `output_format` is hidden from exec-mode schemas — `--json` owns output
                    // encoding. Honor a stray `output_format: "json"` as `--json` instead of
                    // letting the handler skip the formatter only for the result to be
                    // TOON-encoded anyway.
                    let strayOutputFormat: unknown
                    if ('output_format' in input) {
                        ;({ output_format: strayOutputFormat, ...input } = input)
                    }
                    const useJson =
                        forceJson ||
                        strayOutputFormat === 'json' ||
                        tool._meta?.[POSTHOG_META_KEY]?.outputFormat === 'json'
                    // Fold the flag back into the tool's own `output_format` field when it has
                    // one: formatter-toggle tools then skip the server-side formatter (clean raw
                    // JSON, no `__formatted_results_override` duplication), and tools where the
                    // field is a real backend param (dashboard-insights-run) keep full function.
                    const toolSchema = tool.schema
                    if (useJson && schemaHasOutputFormat(toolSchema)) {
                        input.output_format = 'json'
                    }

                    // Same validation gate as the non-exec MCP path (`tool-executor.ts`) —
                    // otherwise bad input reaches the HTTP layer and builds URLs like
                    // `.../actions/undefined/`, a misleading 404 that hides the offending
                    // field. Dispatch the parsed output so coerced values and defaults apply.
                    let validation = toolSchema.safeParse(input, { reportInput: true })
                    if (!validation.success) {
                        const rewrapped = repairArgumentNesting(validation.error, input, toolSchema)
                        if (rewrapped) {
                            input = rewrapped
                            validation = toolSchema.safeParse(input, { reportInput: true })
                        }
                    }
                    if (!validation.success) {
                        const message = formatInputValidationError(tool.name, validation.error, input, tool.schema)
                        trackInnerCall?.(tool.name, {
                            duration_ms: 0,
                            success: false,
                            output_format: useJson ? 'json' : 'text',
                            error_message: message,
                            validation_error: true,
                        })
                        // Typed so the executor's catch skips exception capture and
                        // classifies it as `validation`, not `internal`. The value-free
                        // descriptor rides along so the errored `$mcp_tool_call` records
                        // which field/alias was rejected — without the payload.
                        throw new ToolInputValidationError(
                            message,
                            describeValidationError(validation.error, toolSchema)
                        )
                    }
                    const ignoredKeys = findIgnoredInputKeys(input, validation.data, toolSchema)
                    input = validation.data as Record<string, unknown>

                    const startedAt = Date.now()
                    let result: unknown
                    try {
                        result = withIgnoredInputKeys(
                            markNoncanonicalMetricRun(tool.name, await tool.handler(context, input)),
                            ignoredKeys
                        )
                    } catch (err) {
                        // PostHogValidationError is the API's 400 validation_error body.
                        const apiError = findRecoverableApiError(err)
                        // A skill lookup that misses is not a failure the agent should
                        // read as one. Resolved before the report below, so telemetry
                        // records which kind of miss it was alongside the 404.
                        const lookupMiss = formatSkillLookupMiss(tool.name, err, input, options.builtInSkillHint)
                        trackInnerCall?.(tool.name, {
                            duration_ms: Date.now() - startedAt,
                            success: false,
                            output_format: useJson ? 'json' : 'text',
                            error_message: err instanceof Error ? err.message : String(err),
                            ...(apiError
                                ? { error_status: apiError instanceof PostHogApiError ? apiError.status : 400 }
                                : {}),
                            ...(lookupMiss ? { skill_lookup_miss_kind: lookupMiss.kind } : {}),
                            input,
                            error: err,
                        })
                        if (lookupMiss) {
                            // The success path below serializes a string result under
                            // `--json`, so encode this the same way. A `--json` caller
                            // reaches for `JSON.parse`, and raw prose is the one reply
                            // that would break in its hands.
                            return useJson ? JSON.stringify(lookupMiss.message) : lookupMiss.message
                        }
                        throw err
                    }
                    const durationMs = Date.now() - startedAt
                    // The text path below builds no payload, so emptiness is reported from here.
                    const resultShape = isEmptyToolResult(result, tool.name) ? { result_empty: true } : {}
                    const formattedOverride =
                        result !== null && typeof result === 'object'
                            ? (result as Record<string, unknown>)[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]
                            : undefined
                    const isInformationalResponse =
                        result !== null &&
                        typeof result === 'object' &&
                        (result as Record<string, unknown>)[POSTHOG_INFORMATIONAL_RESPONSE_KEY] === true

                    // Native widgets cannot recover entity data from the optimized text. Preserve
                    // the handler object before exec serializes it, including tools without UI apps.
                    const includeAppData = mcpConsumer === 'posthog_ai'

                    if (useJson && isInformationalResponse && typeof formattedOverride === 'string') {
                        const outputText = JSON.stringify({ content: formattedOverride })
                        trackInnerCall?.(tool.name, {
                            duration_ms: durationMs,
                            success: true,
                            output_format: 'json',
                            input_tokens: estimateTokens(input),
                            output_tokens: estimateTokens(outputText),
                            input,
                            output: outputText,
                            ...resultShape,
                        })
                        if (!includeAppData) {
                            return outputText
                        }
                        // The model still reads only the wrapped text this branch protects, so a
                        // JSON request must not cost widgets the handler object the optimized path
                        // carries. Copying drops the non-enumerable wrapper keys, as the payload
                        // builder does.
                        const appData = Array.isArray(result) ? [...result] : { ...(result as Record<string, unknown>) }
                        return markExecPayload({
                            content: [{ type: 'text', text: outputText }],
                            _meta: { [APP_DATA_META_KEY]: appData as Record<string, unknown> },
                        })
                    }
                    const isInlineUiAppHost = isPostHogCodeConsumer(mcpConsumer) || options.isInlineExecUiHost === true
                    if (includeAppData || (tool._meta?.ui?.resourceUri && isInlineUiAppHost)) {
                        const isStringResult = typeof result === 'string'
                        const distinctId =
                            !isStringResult && tool._meta?.ui?.resourceUri ? await context.getDistinctId() : undefined
                        const payload = markExecPayload(
                            buildToolResultPayload({
                                handlerResult: result,
                                toolMeta: tool._meta,
                                toolName: tool.name,
                                params: useJson ? { ...input, output_format: 'json' } : input,
                                // Inline-exec UI-app hosts (PostHog Desktop, Claude Code)
                                // surface `structuredContent` to the model in preference to the
                                // text content, which would bury a compact formatted table under
                                // the raw JSON. When such a table exists, re-home the UI app's data
                                // onto `_meta` (see APP_DATA_META_KEY) so the model reads the compact
                                // table and the chart still renders. When there is no formatted table,
                                // the payload stays in the standard `structuredContent` field — which
                                // both the model and the app read — and the text channel carries a
                                // pointer rather than a second copy of the same rows.
                                forceUiDataToMeta: true,
                                includeAppData,
                                distinctId,
                                mcpClientName: options.mcpClientName,
                                includeUiResponseMeta: isInlineUiAppHost,
                                includeRenderNote: isInlineUiAppHost,
                            })
                        )
                        trackInnerCall?.(tool.name, {
                            duration_ms: durationMs,
                            success: true,
                            output_format: 'structured',
                            input_tokens: estimateTokens(input),
                            output_tokens: estimateResponseTokens(payload),
                            input,
                            output: payload,
                            ...resultShape,
                        })
                        return payload
                    }

                    // Serialize once so the token estimate measures the exact text
                    // returned to the client, not the raw object.
                    let outputText: string
                    if (useJson) {
                        outputText = JSON.stringify(result)
                    } else {
                        // Optimized mode: when the handler attached a backend-formatted table
                        // via `__formatted_results_override`, return ONLY that string. The raw
                        // `results`/`_posthogUrl` payload would otherwise duplicate the table
                        // and crowd it out — buildToolResultPayload makes the same choice for
                        // the non-exec path, this keeps exec consistent.
                        outputText = typeof formattedOverride === 'string' ? formattedOverride : formatResponse(result)
                    }
                    trackInnerCall?.(tool.name, {
                        duration_ms: durationMs,
                        success: true,
                        output_format: useJson ? 'json' : 'text',
                        input_tokens: estimateTokens(input),
                        output_tokens: estimateTokens(outputText),
                        input,
                        output: outputText,
                        ...resultShape,
                    })
                    return outputText
                }

                default: {
                    // A connected tool reaches `call` through the gateway, not `allTools`.
                    // Only a namespaced name can be one, so a plain typo skips the fetch.
                    const isTool =
                        allTools.some((tool) => tool.name === verb) ||
                        (isGatewayToolName(verb) && (await resolveTools()).some((tool) => tool.name === verb))
                    if (isTool) {
                        throw new ExecCommandError(
                            `"${verb}" is a tool, not a command. Invoke it as: call ${verb} <json_input>. Run "info ${verb}" first if its schema is not in context.`,
                            'tool_as_command'
                        )
                    }
                    throw new ExecCommandError(
                        `Unknown command: "${verb}". Run "help" to list available commands.`,
                        'unknown_command'
                    )
                }
            }
        },
    }
}