Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.5 KB
Raw Blame
import type { AttachedContextItem } from '~/layout/ai/attachedContext'
import { FeatureFlagType } from '~/types'

import { isV1FeatureFlagConfig } from 'products/feature_flags/frontend/featureFlagConfigFormat'

// The backend rejects a text attachment longer than this and fails the whole send with a 400
// (MAX_TEXT_LENGTH in products/posthog_ai/backend/context_wrapper.py), so an oversized flag has to
// lose detail here rather than break the user's message.
const MAX_TARGETING_VALUE_LENGTH = 4096

// A flag's description is free text with no length limit of its own, so it could otherwise eat the
// whole budget above on its own.
const MAX_DESCRIPTION_LENGTH = 400

/**
 * Describes a saved flag to PostHog AI: a keyed reference that renders as the composer chip, plus a
 * separate keyless item carrying the targeting as JSON.
 *
 * These have to stay two items. `formatItem` in posthogContextBlock renders a keyed item as its
 * type, key, and label alone and never reads `value`, so folding the JSON into the reference would
 * drop the targeting before it reached the agent.
 */
export function featureFlagContextItems(featureFlag: FeatureFlagType): AttachedContextItem[] {
    return [
        // `name` on a flag is the description, so the key is the only display name available here.
        { type: 'feature_flag', key: featureFlag.key, pageId: featureFlag.id, label: featureFlag.key },
        { type: 'feature_flag_targeting', label: 'Release conditions', value: targetingValue(featureFlag) },
    ]
}

function targetingValue(featureFlag: FeatureFlagType): string {
    const filters = featureFlag.filters
    if (!isV1FeatureFlagConfig(filters)) {
        const full = JSON.stringify({ key: featureFlag.key, active: featureFlag.active, config: filters })
        return full.length <= MAX_TARGETING_VALUE_LENGTH
            ? full
            : JSON.stringify({ key: featureFlag.key, active: featureFlag.active, config_version: filters.version })
    }
    const identity = {
        key: featureFlag.key,
        description: featureFlag.name.slice(0, MAX_DESCRIPTION_LENGTH),
        active: featureFlag.active,
        // Whether the flag counts persons or a group type, which decides what "who matches?" means.
        aggregation_group_type_index: filters?.aggregation_group_type_index ?? null,
        // The matcher evaluates all three ahead of the release conditions, so an agent reading only
        // those overcounts a flag behind a holdout or an early access gate.
        holdout: filters?.holdout ?? null,
    }

    const full = JSON.stringify({
        ...identity,
        multivariate: filters?.multivariate ?? null,
        super_groups: filters?.super_groups ?? null,
        holdout_groups: filters?.holdout_groups ?? null,
        release_conditions: filters?.groups ?? [],
    })
    if (full.length <= MAX_TARGETING_VALUE_LENGTH) {
        return full
    }

    // Property filters are what blow the budget, because a single condition can hold hundreds of
    // pasted values. Variant keys and the condition counts still describe the flag's shape, and the
    // agent can read the saved flag by key when it needs the filters themselves.
    return JSON.stringify({
        ...identity,
        variant_keys: filters?.multivariate?.variants.map((variant) => variant.key) ?? null,
        release_condition_count: filters?.groups?.length ?? 0,
        super_condition_count: filters?.super_groups?.length ?? 0,
        holdout_condition_count: filters?.holdout_groups?.length ?? 0,
        conditions_omitted: 'Too large to attach. Read the saved flag to see the property filters.',
    })
}

/** Skill the "Review cleanup with AI" action asks PostHog AI to load; bundled into the agent sandbox image. */
export const FEATURE_FLAG_CLEANUP_SKILL = 'cleaning-up-stale-feature-flags'

export const FEATURE_FLAG_CLEANUP_ASSESSMENT_PROMPT = 'Assess this feature flag for cleanup.'
const FEATURE_FLAG_CLEANUP_TARGET_TYPE = 'feature_flag_cleanup_target'

const FEATURE_FLAG_CLEANUP_SKILL_CONTEXT_ITEM: AttachedContextItem = {
    type: 'skill',
    key: FEATURE_FLAG_CLEANUP_SKILL,
    label: 'Cleaning up stale feature flags skill',
}

// Our own static, build-time text only. Never interpolate the flag's key, name, or description into
// this item, or a project-authored string would ride inside the trusted block the agent is told to
// follow. The saved identity a reader needs to act on travels separately, as the untrusted
// `feature_flag_cleanup_target` item below.
const FEATURE_FLAG_CLEANUP_INSTRUCTIONS_CONTEXT_ITEM: AttachedContextItem = {
    type: 'instructions',
    hidden: true,
    value:
        `Load the ${FEATURE_FLAG_CLEANUP_SKILL} skill before assessing. The ${FEATURE_FLAG_CLEANUP_TARGET_TYPE} item ` +
        'names the flag by project, id, and key. Re-fetch its current definition with the feature-flag tools ' +
        'rather than trusting values elsewhere in this conversation, because it can have changed since the page ' +
        'that started this request was loaded. Check linked systems (dependent flags, experiments, holdouts, ' +
        'schedules) and recent activity before concluding. This request is assessment only: return the evidence ' +
        'you gathered, any blockers, and a recommended next step. Do not edit any files, open a pull request, or ' +
        'change this flag in PostHog - do not enable, disable, archive, unarchive, or delete it.',
}

function cleanupTargetValue(featureFlag: Pick<FeatureFlagType, 'id' | 'key'>, projectId: number | null): string {
    return JSON.stringify({ project_id: projectId, id: featureFlag.id, key: featureFlag.key })
}

/** The instruction stays trusted text; the flag identity travels separately as untrusted data. */
export function featureFlagCleanupAssessmentContextItems(
    featureFlag: Pick<FeatureFlagType, 'id' | 'key'>,
    projectId: number | null
): AttachedContextItem[] {
    return [
        FEATURE_FLAG_CLEANUP_SKILL_CONTEXT_ITEM,
        FEATURE_FLAG_CLEANUP_INSTRUCTIONS_CONTEXT_ITEM,
        {
            type: FEATURE_FLAG_CLEANUP_TARGET_TYPE,
            hidden: true,
            value: cleanupTargetValue(featureFlag, projectId),
        },
    ]
}

// `create-feature-flag` is left out because it never targets the flag on screen.
// `delete-feature-flag` and the bulk tools can target it, and are still left out: there is nothing
// to refresh into after a delete, and the bulk tools pass a list of ids that this matcher does not
// read.
export const FEATURE_FLAG_MUTATION_TOOLS = [
    'update-feature-flag',
    'feature-flag-enable',
    'feature-flag-disable',
    'feature-flag-archive',
    'feature-flag-unarchive',
    'feature-flag-restore',
]

// Every mutation tool accepts these spellings for the flag id (`param_overrides.id.aliases` in
// products/feature_flags/mcp/tools.yaml). The MCP server resolves them to `id`, but this matcher
// reads the raw arguments the model wrote. Match all five, or an aliased call never refreshes.
const FLAG_ID_KEYS = ['id', 'flagId', 'flag_id', 'feature_flag_id', 'featureFlagId']

// The bus is global, so an unrelated flag's call arrives here too. The id comes through as a string
// or a number because the tools cast it, and as null args when they could not be parsed.
export function mutationTargetsFeatureFlag(innerInput: Record<string, unknown> | null, flagId: number): boolean {
    return FLAG_ID_KEYS.some((key) => {
        const id = innerInput?.[key]
        if (typeof id !== 'string' && typeof id !== 'number') {
            return false
        }
        return String(id) === String(flagId)
    })
}