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.

4.6 KB
Raw Blame
import { z } from 'zod'

import type { Schemas } from '@/api/generated'
import { ToolInputValidationError } from '@/lib/errors'
import { normalizeParamAliases } from '@/tools/cast-helpers'
import { withConditionIds } from '@/tools/featureFlags/conditionIds'
import { resolveFlagsByKey } from '@/tools/featureFlags/resolveFlagsByKey'
import { withPostHogUrl, type WithPostHogUrl } from '@/tools/tool-utils'
import type { Context, ToolBase } from '@/tools/types'

/**
 * `feature-flag-get-definition-by-key` fetches a flag by its string key.
 *
 * `feature-flag-get-definition` (generated from `feature_flags_retrieve`) only accepts the
 * flag's numeric ID, but the identifier agents naturally have is the key — the string they see
 * in the UI and in code. This hand-written tool resolves a key to its flag via the list
 * endpoint's `key` filter (a case-insensitive exact match), narrowed to the exact-case match
 * when the filter returns more than one case-variant.
 *
 * A key that matches no flag is not an error. The dominant caller is an agent checking whether
 * a flag exists before creating it (a read-before-create existence check), so a miss is the
 * expected answer: it returns a structured `{ found: false }` result naming the key and
 * pointing at the list/create path. The caller's next step, creating the flag, doesn't depend
 * on this being an exception. Reuse this not-found-as-data pattern for other existence checks;
 * keep throwing where the caller expects the target to already exist, so a miss signals a
 * genuine problem rather than an expected outcome.
 */
// Agents composing this call in exec mode reconstruct the param name from the tool
// name rather than reading the advertised schema, and reach for `flagKey` /
// `flag_key` / `feature_flag_key` where the schema requires `key` — production
// traces show that mismatch, not a genuinely absent key, as the dominant
// validation failure. Normalize the aliases onto `key` before validation (same
// pattern as the insight-id aliases; see normalizeParamAliases). The canonical
// `key` still wins on conflict, and the advertised JSON schema is unchanged —
// preprocess renders as the wrapped object, so it still shows only `key`.
const schema = z.preprocess(
    normalizeParamAliases({ key: ['flagKey', 'flag_key', 'feature_flag_key', 'featureFlagKey'] }),
    z.object({
        key: z.string().describe('The feature flag key: the string identifier used in code (e.g. "new-checkout").'),
    })
)

type Params = z.infer<typeof schema>

/** The result shape returned when no flag matches `key`. See the file doc comment for why this is data, not a thrown error. */
interface FeatureFlagLookupMiss {
    found: false
    key: string
    message: string
}

/** Discriminate on `found` in both branches, so callers don't have to test for its absence on a match. */
type Result = (WithPostHogUrl<Schemas.FeatureFlag> & { found: true }) | FeatureFlagLookupMiss

const featureFlagGetDefinitionByKey = (): ToolBase<typeof schema, Result> => ({
    name: 'feature-flag-get-definition-by-key',
    schema,
    handler: async (context: Context, params: Params) => {
        const key = params.key.trim()
        if (key === '') {
            throw new ToolInputValidationError('Provide the feature flag key to fetch.')
        }

        const projectId = await context.stateManager.getProjectId()

        const matches = await resolveFlagsByKey(context, projectId, key)

        if (matches.length === 0) {
            return {
                found: false,
                key,
                message:
                    `No feature flag with key "${key}" exists in this project. ` +
                    'Create it with `create-feature-flag`, or call `feature-flag-get-all` to list existing flags.',
            }
        }
        if (matches.length > 1) {
            // Unlike a miss, this is still an error: the key is ambiguous and the agent can't
            // proceed on its own — it needs the numeric id from a different tool call.
            const ids = matches.map((flag) => flag.id).join(', ')
            throw new ToolInputValidationError(
                `Multiple feature flags matched key "${key}" (IDs: ${ids}). Pass the numeric \`id\` to ` +
                    'feature-flag-get-definition instead.'
            )
        }
        const flag = matches[0]!
        // The list row is already the full flag, so it's wrapped directly instead of
        // triggering a redundant fetch-by-id round trip.
        const flagWithUrl = await withPostHogUrl(context, flag, `/feature-flags/${flag.id}`)
        return { ...withConditionIds(flagWithUrl), found: true }
    },
})

export default featureFlagGetDefinitionByKey