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.

25.2 KB
Raw Blame
import type { StateLookupCache } from '@/lib/cache/StateLookupCache'
import { MCPClientProfile } from '@/lib/client-detection'
import { isCloudApi, isLocalApi, MCP_GATEWAY_FLAG } from '@/lib/constants'
import { env } from '@/lib/env'
import { McpSessionResetRequiredError } from '@/lib/errors'
import { EVENT_SOURCE, resolveEventSource } from '@/lib/event-source'
import { buildMCPAnalyticsGroups, type MCPAnalyticsContext } from '@/lib/posthog/analytics'
import {
    type EvaluatedFlags,
    evaluateFeatureFlags,
    type FlagEvaluation,
    type FlagGroups,
    resolveFeatureFlagOverrides,
} from '@/lib/posthog/flags'
import type { RequestProperties } from '@/lib/request-properties'
import { filterStaffOnlyTools } from '@/lib/staff-only-tools'
import type { McpMode } from '@/lib/utils'
import { TASKS_CONTEXT_TOOL_NAMES } from '@/tools/tasksContext'
import {
    type FlagGatedTool,
    getFlagGatedTools,
    getRequiredFeatureFlags,
    getScopeGatedTools,
    type ScopeGatedTool,
} from '@/tools/toolDefinitions'
import type { BusinessKnowledgeContent, Context, Env, PinnedActiveContext, Tool, ZodObjectAny } from '@/tools/types'

import { McpSessionRedisStore } from './cache/McpSessionRedisStore'
import type { RedisLike } from './cache/RedisCache'
import { MCP_EXEC_SKILLS_FEATURE_FLAG, MCP_INBOX_FIRST_FLAG } from './constants'
import { GUIDANCE_RULE_FLAGS } from './guidance/rules'
import { MCP_INTENT_PROMPT_FLAG, resolveIntentPrompt } from './intent-prompt'
import {
    type InterviewRecruitmentConfig,
    type InterviewRecruitmentDiagnostics,
    type InterviewRecruitmentUnavailableReason,
    resolveInterviewRecruitmentConfig,
    MCP_INTERVIEW_RECRUITMENT_FLAG,
} from './interview-recruitment'
import {
    buildMCPRequestContext,
    getEffectiveMCPClientContext,
    getEffectiveMCPClientIdentity,
    type MCPRequestContext,
    type MCPSessionContext,
} from './mcp-context'
import { RequestContext } from './request-context'
import type { ToolCatalog } from './tool-catalog'

// ─── Per-request resolved state ───

export interface ResolvedState {
    reqCtx: RequestContext
    context: Context
    useSingleExec: boolean
    viaMcpStore?: boolean | undefined
    toolFeatureFlags: EvaluatedFlags | undefined
    interviewRecruitmentConfig?: InterviewRecruitmentConfig
    intentPrompt?: string
    interviewRecruitmentUnavailableReason?: InterviewRecruitmentUnavailableReason
    interviewRecruitmentDiagnostics?: InterviewRecruitmentDiagnostics
    apiKeyScopes: string[]
    isImpersonated?: boolean
    suppressAnalytics?: boolean
    /**
     * The workspace context that the flags were resolved against.
     * A handler such as `switch-project` changes the live context, so tool-call analytics
     * read this snapshot to keep the project group consistent with the variant.
     */
    analyticsContext?: MCPAnalyticsContext | undefined
    /** Set on the per-call state: whether the client sent a session or conversation handle. */
    carriedContextHandle?: boolean | undefined
    /** The organization's AI data processing consent; undefined when the org could not be read. */
    aiConsentGiven?: boolean | undefined
    /** Read only when a business knowledge search tool is advertised; undefined when unread. */
    businessKnowledgeContent?: BusinessKnowledgeContent | undefined
    oauthClientId: string | undefined
    clientProfile: MCPClientProfile
    requestContext: MCPRequestContext
    sessionContext: MCPSessionContext | null
    allTools: Tool<ZodObjectAny>[]
    scopeGatedTools: ScopeGatedTool[]
    findScopeGatedTool: (name: string) => ScopeGatedTool | undefined
    flagGatedTools: FlagGatedTool[]
    /**
     * The tools a scout run with a picked tool list holds, from token introspection.
     * Undefined means no per-tool policy. Every other tool is hidden, and exec refuses it
     * as `tool_not_granted`.
     */
    heldTools?: ReadonlySet<string> | undefined
    /** The task a sandbox token is bound to, from token introspection. */
    sandboxTaskId?: string | undefined
    supportsStepUp: boolean
    /**
     * Whether the caller's team may reach third-party MCP tools through `exec`.
     * Gated on the same flag as the gateway UI — the tools are the gateway's payoff,
     * so they roll out together. Also forced off in read-only mode: a connected
     * server's tools can mutate and PostHog can't prove otherwise, so the catalog's
     * read-only filter has no equivalent to apply to them.
     *
     * Deliberately not folded into `allTools`: `instructions.ts` looks every entry up in
     * the static tool-definition registry (which throws on an unknown name) and renders
     * the full roster into the instructions payload.
     */
    gatewayToolsEnabled: boolean
    gatewayToolFilter?: Pick<RequestProperties, 'tools' | 'features' | 'excludeTools'> | undefined
    distinctId: string
    renderUiEnabled: boolean
}

// ─── Pure helpers ───

export function resolveMode(args: { mode: McpMode | undefined; clientProfile: MCPClientProfile }): {
    mode: McpMode
    useSingleExec: boolean
} {
    const { mode, clientProfile } = args
    // CLI (single-exec) is the default; only allow-listed clients (Cursor) keep
    // the full per-tool roster, and an explicit ?mode= / x-posthog-mcp-mode
    // header always wins over auto-detection.
    const resolved: McpMode = mode ?? (clientProfile.isToolsModeClient() ? 'tools' : 'cli')
    return { mode: resolved, useSingleExec: resolved === 'cli' }
}

export function tasksContextToolsToExclude(clientProfile: MCPClientProfile, taskId: string | undefined): string[] {
    return clientProfile.isPostHogCodeConsumer() && taskId ? [] : [...TASKS_CONTEXT_TOOL_NAMES]
}

/**
 * Which navigation switch tools to hide given the context the client explicitly
 * pinned via request params.
 *
 * Pinning fixes the *default* active context — it must not disable navigation.
 * Only an explicitly pinned organization is a hard lock: the client asked to
 * operate inside one org, so `switch-organization` is dropped while project
 * switching stays available. A pinned *project* excludes nothing, because the
 * documented cross-org flow depends on it: from an active project an agent
 * resolves an org via `organizations-get`, calls `switch-organization`, then
 * `switch-project` to reach a project in another organization (see the
 * `switch-project` tool description). Excluding the switch tools on a project
 * pin — which nearly every connection sends — made that flow impossible.
 *
 * Note this only affects keys that can act across orgs. A project-scoped key
 * (`scoped_teams`) never sees `switch-organization` regardless, because
 * `getToolsForFeatures` independently strips every `organization:*` tool the
 * backend would 403 for such a token.
 */
export function switchToolsToExclude(pinned: { organizationId?: string | undefined }): string[] {
    return pinned.organizationId ? ['switch-organization'] : []
}

// ─── Resolver ───

// Task origins whose sandbox mounts every shared gateway server as its own MCP server
// (`mcp__<server>__<tool>`). Surfacing the same tools through `exec` as `<slug>__<tool>` gives
// those agents a second, member-scoped name for each tool — one that resolves for a person
// running the task interactively and comes back empty for the service account the scheduled
// run uses, so instructions learned on one path silently fail on the other.
const DIRECT_GATEWAY_MOUNT_ORIGINS: ReadonlySet<string> = new Set(['signals_scout'])

const BUSINESS_KNOWLEDGE_SEARCH_TOOLS: ReadonlySet<string> = new Set([
    'business-knowledge-documents-search',
    'business-knowledge-repositories-search',
])

function mountsGatewayServersDirectly(taskOriginProduct: string | undefined): boolean {
    return taskOriginProduct !== undefined && DIRECT_GATEWAY_MOUNT_ORIGINS.has(taskOriginProduct)
}

export class RequestStateResolver {
    private readonly catalog: ToolCatalog
    private readonly redis: RedisLike
    private readonly env: Env

    constructor(catalog: ToolCatalog, redis: RedisLike, env: Env) {
        this.catalog = catalog
        this.redis = redis
        this.env = env
    }

    async resolve(props: RequestProperties, lookups?: StateLookupCache): Promise<ResolvedState> {
        const requestContext = buildMCPRequestContext(props)
        const reqCtx = new RequestContext(this.redis, this.env, props, requestContext, lookups)

        const { features, tools, organizationId, projectId, readOnly } = props
        const pinned = await this.resolvePinnedContext(reqCtx, { organizationId, projectId })
        reqCtx.setPinnedContext(pinned)

        // Start Redis reads only when Promise.all can observe their timeout rejections.
        // A pinned request never writes a default into the token selection that other sessions share.
        const [context, sessionContext, storedProjectId] = await Promise.all([
            reqCtx.getContext(),
            this.resolveSessionContext(requestContext),
            pinned ? undefined : reqCtx.tokenCache.get('projectId'),
        ])
        const needsDefaultContext = pinned
            ? pinned.sessionScoped && !pinned.orgId && !pinned.projectId
            : !storedProjectId
        if (needsDefaultContext) {
            await context.stateManager.setDefaultOrganizationAndProject()
        }
        const clientContext = getEffectiveMCPClientContext(requestContext, sessionContext)

        // MCP_GATEWAY_FLAG gates no tool of its own — it gates the third-party tools `exec`
        // resolves — so the tool-definition scan can't discover it; join it in explicitly.
        // MCP_EXEC_SKILLS_FEATURE_FLAG gates the `learn` skill commands, and MCP_INBOX_FIRST_FLAG a prompt section.
        const allFlagKeys = [
            ...new Set([
                ...getRequiredFeatureFlags(),
                MCP_GATEWAY_FLAG,
                MCP_EXEC_SKILLS_FEATURE_FLAG,
                MCP_INTERVIEW_RECRUITMENT_FLAG,
                MCP_INTENT_PROMPT_FLAG,
                MCP_INBOX_FIRST_FLAG,
                ...GUIDANCE_RULE_FLAGS,
            ]),
        ]

        const flagAnalyticsContext = await reqCtx.safelyGetAnalyticsContext(context)
        const flagGroups = flagAnalyticsContext ? buildMCPAnalyticsGroups(flagAnalyticsContext) : undefined

        const [{ flags: allFlags, payloads }, _apiKey, distinctId] = await Promise.all([
            this.resolveAllFlags(reqCtx, allFlagKeys, flagGroups),
            context.stateManager.getApiKey(),
            reqCtx.getDistinctId(),
        ])
        const [oauthClientName, oauthClientId] = await Promise.all([
            reqCtx.tokenCache.get('clientName'),
            reqCtx.tokenCache.get('oauthClientId'),
        ])
        props.suppressAnalytics = _apiKey?.suppress_analytics === true
        const liveClient = getEffectiveMCPClientIdentity(requestContext, sessionContext)
        const source = resolveEventSource({
            mcpConsumer: liveClient.mcpConsumer,
            clientUserAgent: props.clientUserAgent,
            apiKeyScopes: _apiKey?.scopes,
            oauthClientId: oauthClientId || undefined,
        })

        // Dev/test-only overrides win over evaluated values (no-op in production).
        const overrides = resolveFeatureFlagOverrides(props.featureFlagOverrides)
        const mergedFlags = { ...allFlags, ...overrides }
        let recruitmentPayload = payloads[MCP_INTERVIEW_RECRUITMENT_FLAG]
        if (
            recruitmentPayload === undefined &&
            isLocalApi() &&
            (env.NODE_ENV === 'development' || env.NODE_ENV === 'test') &&
            overrides[MCP_INTERVIEW_RECRUITMENT_FLAG]
        ) {
            try {
                recruitmentPayload = JSON.parse(env.MCP_INTERVIEW_RECRUITMENT_PAYLOAD ?? '')
            } catch {
                // Local opt-in still requires explicit, valid invitation content.
            }
        }
        const recruitmentFlagValue = mergedFlags[MCP_INTERVIEW_RECRUITMENT_FLAG]
        let interviewRecruitmentUnavailableReason: InterviewRecruitmentUnavailableReason | undefined
        if (source !== EVENT_SOURCE.MCP) {
            interviewRecruitmentUnavailableReason = 'surface_excluded'
        } else if (_apiKey?.scopes?.includes('internal_run:read')) {
            interviewRecruitmentUnavailableReason = 'internal_run'
        } else if (props.taskId || props.taskOriginProduct) {
            interviewRecruitmentUnavailableReason = 'task_bound'
        } else if (recruitmentFlagValue === undefined) {
            interviewRecruitmentUnavailableReason = 'flag_unavailable'
        } else if (recruitmentFlagValue === false) {
            interviewRecruitmentUnavailableReason = 'flag_disabled'
        }
        const interviewRecruitmentConfig = interviewRecruitmentUnavailableReason
            ? undefined
            : resolveInterviewRecruitmentConfig(recruitmentFlagValue, recruitmentPayload)
        if (!interviewRecruitmentUnavailableReason && !interviewRecruitmentConfig) {
            interviewRecruitmentUnavailableReason = 'invalid_configuration'
        }
        // Preserve variant strings (and `undefined` for unevaluated flags) — the
        // tool filter needs raw values to support `feature_flag_variant` matching.
        // Include override keys so a forced flag reaches the tool/instructions layer
        // even when no catalog tool referenced it.
        const flagKeysForState = [...new Set([...allFlagKeys, ...Object.keys(overrides)])]
        const toolFeatureFlags = Object.fromEntries(flagKeysForState.map((k) => [k, mergedFlags[k]]))
        const intentPrompt =
            source === EVENT_SOURCE.MCP && !_apiKey?.is_impersonated && !props.suppressAnalytics
                ? resolveIntentPrompt(mergedFlags[MCP_INTENT_PROMPT_FLAG], payloads[MCP_INTENT_PROMPT_FLAG])
                : undefined

        const clientProfile = new MCPClientProfile({
            clientName: clientContext.mcpClientName,
            clientVersion: clientContext.mcpClientVersion,
            consumer: clientContext.mcpConsumer,
            oauthClientName: oauthClientName || undefined,
            vendorClient: clientContext.mcpVendorClient,
            userAgent: props.clientUserAgent,
            uiSupported: requestContext.mcpUiSupported ?? sessionContext?.mcpUiSupported,
        })

        const renderUiEnabled = clientProfile.isRenderUiHost()

        const { mode: resolvedMode, useSingleExec } = resolveMode({
            mode: requestContext.mode,
            clientProfile,
        })
        requestContext.mode = resolvedMode
        reqCtx.setMcpContexts(requestContext, sessionContext)
        props.mode = resolvedMode

        const apiKeyScopes = _apiKey?.scopes ?? []
        const apiKeyScopedTeams = _apiKey?.scoped_teams ?? []
        const aiConsentGiven = await context.stateManager.getAiConsentGiven()
        const availableFeatures = await context.stateManager.getAvailableFeatures()
        const isCloud = isCloudApi()

        const excludeTools = [
            ...switchToolsToExclude({ organizationId }),
            ...tasksContextToolsToExclude(clientProfile, props.taskId),
            ...(apiKeyScopes.includes('internal_run:read') ? ['tasks-run-create', 'tasks-create-and-run'] : []),
            ...(props.excludeTools ?? []),
        ]

        const filterOptions = {
            features,
            tools,
            excludeTools,
            readOnly,
            featureFlags: toolFeatureFlags,
            scopedTeams: apiKeyScopedTeams,
            aiConsentGiven: aiConsentGiven ?? undefined,
            availableFeatures,
            isCloud,
        }
        // The held set is a server-derived ceiling on top of every other filter, so a tool
        // outside it is neither listed nor offered as a gated hint the agent could chase.
        const heldTools = _apiKey?.mcp_allowed_tools ? new Set(_apiKey.mcp_allowed_tools) : undefined
        const isHeld = (tool: { name: string }): boolean => !heldTools || heldTools.has(tool.name)

        // Staff-only tools (OAuth-hidden scopes) need the extra explicit-scope +
        // is_staff gate on top of the catalog's plain scope filter.
        const allTools = (
            await filterStaffOnlyTools(
                this.catalog.getFilteredTools({ ...filterOptions, scopes: apiKeyScopes }),
                _apiKey ?? { scopes: [] },
                () => context.stateManager.getUser()
            )
        ).filter(isHeld)
        const businessKnowledgeContent = allTools.some(({ name }) => BUSINESS_KNOWLEDGE_SEARCH_TOOLS.has(name))
            ? await this.resolveBusinessKnowledgeContent(context)
            : undefined
        // Scope-gated hints are only consumed by the exec `search` command, which
        // only exists in single-exec mode — skip the extra scan otherwise.
        const scopeGatedTools = useSingleExec ? getScopeGatedTools(apiKeyScopes, filterOptions).filter(isHeld) : []
        // A call to a gated tool reports the missing scope before the tool runs. Tools mode builds
        // the list only on the first miss instead of scanning the catalog on every request.
        let toolsModeScopeGatedTools: ScopeGatedTool[] | undefined
        const findScopeGatedTool = (name: string): ScopeGatedTool | undefined =>
            (useSingleExec
                ? scopeGatedTools
                : (toolsModeScopeGatedTools ??= getScopeGatedTools(apiKeyScopes, filterOptions).filter(isHeld))
            ).find((tool) => tool.name === name)
        // Only exec redirects a call to a gated tool; tools mode just omits it.
        const flagGatedTools = useSingleExec ? getFlagGatedTools(filterOptions).filter(isHeld) : []

        return {
            reqCtx,
            context,
            useSingleExec,
            viaMcpStore: props.viaMcpStore,
            toolFeatureFlags,
            interviewRecruitmentConfig,
            intentPrompt,
            interviewRecruitmentUnavailableReason,
            apiKeyScopes,
            isImpersonated: _apiKey?.is_impersonated === true,
            suppressAnalytics: props.suppressAnalytics,
            analyticsContext: flagAnalyticsContext,
            aiConsentGiven: aiConsentGiven ?? undefined,
            businessKnowledgeContent,
            oauthClientId: oauthClientId || undefined,
            clientProfile,
            requestContext,
            sessionContext,
            allTools,
            scopeGatedTools,
            findScopeGatedTool,
            flagGatedTools,
            gatewayToolFilter: { tools, features, excludeTools },
            heldTools,
            sandboxTaskId: _apiKey?.sandbox_task_id,
            supportsStepUp: _apiKey?.supports_step_up === true,
            gatewayToolsEnabled:
                useSingleExec &&
                !readOnly &&
                mergedFlags[MCP_GATEWAY_FLAG] === true &&
                !mountsGatewayServersDirectly(props.taskOriginProduct),
            distinctId,
            renderUiEnabled,
        }
    }

    /**
     * Capture the session selection once per request so another connection's
     * switches cannot redirect an in-flight call. A resent pin preserves switches;
     * a changed pin replaces the whole selection. Clients may send pins only on initialize.
     */
    private async resolvePinnedContext(
        reqCtx: RequestContext,
        pin: { organizationId?: string | undefined; projectId?: string | undefined }
    ): Promise<PinnedActiveContext | undefined> {
        const { organizationId, projectId } = pin
        const hasPin = Boolean(organizationId || projectId)

        const sessionCache = reqCtx.sessionScopedCache
        if (!sessionCache) {
            return hasPin ? { pin, sessionScoped: false, orgId: organizationId, projectId } : undefined
        }

        const legacyCache = reqCtx.legacySessionScopedCache
        const [appliedPinOrg, appliedPinProject, activeOrg, activeProject, defaults, legacyPinOrg, legacyPinProject] =
            await Promise.all([
                sessionCache.get('appliedPinOrgId'),
                sessionCache.get('appliedPinProjectId'),
                sessionCache.get('activeOrgId'),
                sessionCache.get('activeProjectId'),
                sessionCache.get('defaultContext'),
                legacyCache?.get('appliedPinOrgId'),
                legacyCache?.get('appliedPinProjectId'),
            ])
        // A pin marker under the former key means a pinned session from before the
        // key included the credential. Its saved switch would be lost silently, so
        // stop before any tool runs. Legacy state without a pin marker never changed
        // the selection, so it needs no reset.
        const hasSessionState = Boolean(appliedPinOrg || appliedPinProject || activeOrg || activeProject || defaults)
        if (!hasSessionState && (legacyPinOrg || legacyPinProject)) {
            throw new McpSessionResetRequiredError()
        }
        // These keys carry a write-based TTL, but the MCP session they belong to
        // renews its own context store on every request. Renew them too, so a
        // switch recorded early in a long-lived session does not expire before
        // the session ends and read back as a missing marker — which reads as a
        // changed pin, discards the switch, and reverts to the pin mid-session.
        await sessionCache.refreshTtl([
            'appliedPinOrgId',
            'appliedPinProjectId',
            'activeOrgId',
            'activeProjectId',
            'defaultContext',
            'defaultProjectId',
        ])

        // An omitted pin is not a changed pin: keep the session's saved context.
        if (!hasPin) {
            const useDefaults =
                activeOrg === undefined && activeProject === undefined && !appliedPinOrg && !appliedPinProject
            return {
                pin: { organizationId: appliedPinOrg, projectId: appliedPinProject },
                sessionScoped: true,
                orgId:
                    activeOrg !== undefined
                        ? (activeOrg ?? undefined)
                        : (appliedPinOrg ?? (useDefaults ? defaults?.organizationId : undefined)),
                projectId:
                    activeProject !== undefined
                        ? (activeProject ?? undefined)
                        : (appliedPinProject ?? (useDefaults ? defaults?.projectId?.toString() : undefined)),
            }
        }

        const pinChanged = appliedPinOrg !== organizationId || appliedPinProject !== projectId

        let overrideOrg = activeOrg
        let overrideProject = activeProject
        if (pinChanged) {
            overrideOrg = undefined
            overrideProject = undefined
            await Promise.all([
                sessionCache.delete('activeOrgId'),
                sessionCache.delete('activeProjectId'),
                organizationId ? undefined : sessionCache.delete('appliedPinOrgId'),
                projectId ? undefined : sessionCache.delete('appliedPinProjectId'),
                sessionCache.setMany({
                    ...(organizationId ? { appliedPinOrgId: organizationId } : {}),
                    ...(projectId ? { appliedPinProjectId: projectId } : {}),
                }),
            ])
        }

        return {
            pin,
            sessionScoped: true,
            orgId: overrideOrg !== undefined ? (overrideOrg ?? undefined) : organizationId,
            projectId: overrideProject !== undefined ? (overrideProject ?? undefined) : projectId,
        }
    }

    private async resolveBusinessKnowledgeContent(context: Context): Promise<BusinessKnowledgeContent | undefined> {
        try {
            const projectId = await context.stateManager.getProjectId()
            return await context.stateManager.getOrFetchBusinessKnowledgeContent(projectId)
        } catch {
            return undefined
        }
    }

    private async resolveSessionContext(requestContext: MCPRequestContext): Promise<MCPSessionContext | null> {
        if (!requestContext.mcpSessionId) {
            return null
        }
        return new McpSessionRedisStore(this.redis, requestContext.mcpSessionId).resolve(requestContext)
    }

    private async resolveAllFlags(
        reqCtx: RequestContext,
        flagKeys: string[],
        groups?: FlagGroups
    ): Promise<FlagEvaluation> {
        if (flagKeys.length === 0) {
            return { flags: {}, payloads: {} }
        }
        // Enable product surfaces locally because the analytics flag client is disabled there.
        // Recruitment, intent, guidance and Inbox-first experiments stay off so ordinary development keeps the default behavior.
        if (isLocalApi()) {
            return {
                flags: Object.fromEntries(
                    flagKeys.map((key) => [
                        key,
                        key !== MCP_INTERVIEW_RECRUITMENT_FLAG &&
                            key !== MCP_INTENT_PROMPT_FLAG &&
                            key !== MCP_INBOX_FIRST_FLAG &&
                            !GUIDANCE_RULE_FLAGS.includes(key),
                    ])
                ),
                payloads: {},
            }
        }
        try {
            const distinctId = await reqCtx.getDistinctId()
            const key = JSON.stringify([
                'featureFlags',
                distinctId,
                Object.entries(groups ?? {}).sort(([a], [b]) => a.localeCompare(b)),
                [...flagKeys].sort(),
            ])
            return await reqCtx.lookups.get(reqCtx.tokenCache.scope, key, () =>
                evaluateFeatureFlags(flagKeys, distinctId, groups)
            )
        } catch {
            return { flags: {}, payloads: {} }
        }
    }
}