: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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)
})
}