: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
fix(mcp): hold the guidance cap for the whole conversation (#129492)
Adam Bowker382265f74b53
diff --git a/services/mcp/src/hono/guidance/engine.ts b/services/mcp/src/hono/guidance/engine.tsindex 80c7339592a8..6e65e17d5901 100644--- a/services/mcp/src/hono/guidance/engine.ts+++ b/services/mcp/src/hono/guidance/engine.ts@@ -14,6 +14,12 @@ import { GUIDANCE_RULES, type GuidanceRule } from './rules'const SESSION_TTL_SECONDS = 24 * 60 * 60const CALLER_TTL_SECONDS = 30 * 60+interface CountingScopes {+ primary: string+ ttl: number+ mirror?: string+}+export interface GuidanceCall {/** The effective tool name: the inner tool for an exec `call`, `exec` for other verbs. */toolName: string@@ -97,6 +103,7 @@ function ruleApplies(rule: GuidanceRule, state: ResolvedState, preset: string):// One script per rule, so a concurrent batch cannot reserve the same notice twice. The shown// key counts reports of either kind, so a suppressed outcome that loses the call to another// rule stays pending and is reported on the next matching call instead of being dropped.+// Mirror mode only records a call that another scope decided, so it never reports a notice itself.const RULE_STATE_SCRIPT = `local ttl = tonumber(ARGV[1])if ARGV[4] == 'suppress' then@@ -109,6 +116,13 @@ local matched = redis.call('INCR', KEYS[1])redis.call('EXPIRE', KEYS[1], ttl)redis.call('EXPIRE', KEYS[2], ttl)redis.call('EXPIRE', KEYS[3], ttl)+if ARGV[4] == 'mirror' then+ if ARGV[5] == '1' then+ redis.call('INCR', KEYS[3])+ redis.call('EXPIRE', KEYS[3], ttl)+ end+ return 0+endif ARGV[5] ~= '1' or matched < tonumber(ARGV[2]) thenreturn 0end@@ -146,13 +160,10 @@ export class GuidanceEngine {return undefined}try {- const sessionKey = await this.resolveCountingKey(state)- const ttl = sessionKey ? SESSION_TTL_SECONDS : CALLER_TTL_SECONDS- // The braces are a cluster hash tag, so the script can touch a rule's three keys together.- const scope = `mcp:guidance:{${hashKey(`${state.distinctId}|${sessionKey ?? ''}`)}}`+ const scopes = countingScopes(state)let winner: GuidanceNotice | undefinedfor (const rule of rules) {- const result = await this.touchRule(rule, scope, ttl, call, winner === undefined)+ const result = await this.touchRule(rule, scopes, call, winner === undefined)if (result === RuleResult.Fired) {const outcome = firedOutcome(rule, state)winner = {@@ -175,27 +186,9 @@ export class GuidanceEngine {}}- // A call that carries no handle counts under the caller, because the SDK mints a handle on- // every such call and a client that never echoes one would otherwise never reach a threshold.- // The minted handle is aliased to the caller, so a client that does echo it keeps the counters- // and suppression the conversation started with instead of restarting under the handle.- private async resolveCountingKey(state: ResolvedState): Promise<string | undefined> {- const handle = resolveSessionKey(state.requestContext)- if (!handle) {- return undefined- }- const aliasKey = `mcp:guidance:alias:{${hashKey(`${state.distinctId}|${handle}`)}}`- if (state.carriedContextHandle === false) {- await this.redis.set(aliasKey, '1', 'EX', SESSION_TTL_SECONDS)- return undefined- }- return (await this.redis.get(aliasKey)) === '1' ? undefined : handle- }-private async touchRule(rule: GuidanceRule,- scope: string,- ttl: number,+ scopes: CountingScopes,call: GuidanceCall,canFire: boolean): Promise<RuleResult> {@@ -203,6 +196,32 @@ export class GuidanceEngine {if (!suppressing && !triggerMatches(rule, call)) {return RuleResult.None}+ const result = await this.runRuleScript(+ rule,+ scopes.primary,+ scopes.ttl,+ suppressing ? 'suppress' : 'match',+ canFire+ )+ if (scopes.mirror) {+ await this.runRuleScript(+ rule,+ scopes.mirror,+ SESSION_TTL_SECONDS,+ suppressing ? 'suppress' : 'mirror',+ result !== RuleResult.None+ )+ }+ return result+ }++ private async runRuleScript(+ rule: GuidanceRule,+ scope: string,+ ttl: number,+ mode: 'match' | 'suppress' | 'mirror',+ flag: boolean+ ): Promise<RuleResult> {const key = (suffix: string): string => `${scope}:${rule.id}:${suffix}`const fired = await this.redis.eval(RULE_STATE_SCRIPT,@@ -213,13 +232,32 @@ export class GuidanceEngine {ttl,rule.threshold,rule.maxPerSession,- suppressing ? 'suppress' : 'match',- canFire ? '1' : '0'+ mode,+ flag ? '1' : '0')return Number(fired) as RuleResult}}+// A call with a minted handle counts under the caller, because a client that never echoes gets a new+// handle on every call. It also records under the handle, so a client that echoes keeps its own counters.+function countingScopes(state: ResolvedState): CountingScopes {+ const handle = resolveSessionKey(state.requestContext)+ const callerScope = scopeKey(state.distinctId, undefined)+ if (!handle) {+ return { primary: callerScope, ttl: CALLER_TTL_SECONDS }+ }+ const handleScope = scopeKey(state.distinctId, handle)+ return state.carriedContextHandle === false+ ? { primary: callerScope, ttl: CALLER_TTL_SECONDS, mirror: handleScope }+ : { primary: handleScope, ttl: SESSION_TTL_SECONDS }+}++// The braces are a cluster hash tag, so the script can touch a rule's three keys together.+function scopeKey(distinctId: string, handle: string | undefined): string {+ return `mcp:guidance:{${hashKey(`${distinctId}|${handle ?? ''}`)}}`+}+function firedOutcome(rule: GuidanceRule, state: ResolvedState): GuidanceOutcome {if (rule.requiresAiConsent && state.aiConsentGiven !== true) {return 'no_consent'diff --git a/services/mcp/tests/hono/guidance-engine.test.ts b/services/mcp/tests/hono/guidance-engine.test.tsindex 06c56ab9aaa0..49507fe9e7f5 100644--- a/services/mcp/tests/hono/guidance-engine.test.ts+++ b/services/mcp/tests/hono/guidance-engine.test.ts@@ -144,6 +144,47 @@ describe('GuidanceEngine', () => {expected)})++ describe('with a notice that fires on the first match', () => {+ const firstMatchRule: GuidanceRule = { ...rule, threshold: 1 }++ it.each([+ ['after the caller counters expire', [31]],+ ['after the first day of a busy conversation', Array.from({ length: 80 }, () => 20)],+ ])('keeps the per-conversation cap %s', async (_label, gapsInMinutes) => {+ const redis = makeGuidanceRedis()+ const engine = new GuidanceEngine(redis, [firstMatchRule])+ const outcomes = await run(engine, withHandle('minted-1', false), [replayQuery])+ for (const minutes of gapsInMinutes) {+ redis.advance(minutes * 60)+ outcomes.push(...(await run(engine, withHandle('minted-1', true), [replayQuery])))+ }+ expect(outcomes.filter(Boolean)).toEqual(['test-rule:shown'])+ })++ it('gives a second conversation its own notice once it echoes its handle', async () => {+ const engine = new GuidanceEngine(makeGuidanceRedis(), [firstMatchRule])+ await run(engine, withHandle('minted-1', false), [replayQuery])+ await expect(run(engine, withHandle('minted-2', false), [replayQuery])).resolves.toEqual([undefined])+ await expect(run(engine, withHandle('minted-2', true), [replayQuery, replayQuery])).resolves.toEqual([+ 'test-rule:shown',+ undefined,+ ])+ })++ it('does not repeat in the conversation that already got the notice from the caller counters', async () => {+ const engine = new GuidanceEngine(makeGuidanceRedis(), [firstMatchRule])+ await run(engine, withHandle('minted-1', false), [replayQuery])+ await run(engine, withHandle('minted-2', false), [replayQuery])+ await expect(run(engine, withHandle('minted-1', true), [replayQuery])).resolves.toEqual([undefined])+ })++ it('caps a client that never echoes under the caller', async () => {+ const engine = new GuidanceEngine(makeGuidanceRedis(), [firstMatchRule])+ await run(engine, withHandle('minted-1', false), [replayQuery])+ await expect(run(engine, withHandle('minted-2', false), [replayQuery])).resolves.toEqual([undefined])+ })+ })})it('reports a suppressed outcome on a later call when another rule wins the threshold call', async () => {diff --git a/services/mcp/tests/hono/helpers/guidance-redis-stubs.ts b/services/mcp/tests/hono/helpers/guidance-redis-stubs.tsindex 651f93cdcc75..18424b512e6d 100644--- a/services/mcp/tests/hono/helpers/guidance-redis-stubs.ts+++ b/services/mcp/tests/hono/helpers/guidance-redis-stubs.ts@@ -3,11 +3,21 @@ import type { RedisLike } from '@/hono/cache/RedisCache'export interface GuidanceRedisStub extends RedisLike {store: Map<string, string>evalCalls: (string | number)[][]+ advance(seconds: number): void}export function makeGuidanceRedis(failing = false): GuidanceRedisStub {const store = new Map<string, string>()const evalCalls: (string | number)[][] = []+ const expiresAt = new Map<string, number>()+ let now = 0+ const refresh = (keys: (string | undefined)[], ttl: number): void => {+ for (const key of keys) {+ if (key !== undefined && store.has(key)) {+ expiresAt.set(key, now + ttl)+ }+ }+ }const guard = async <T>(value: T): Promise<T> => {if (failing) {throw new Error('redis down')@@ -22,9 +32,21 @@ export function makeGuidanceRedis(failing = false): GuidanceRedisStub {return {store,evalCalls,+ advance: (seconds) => {+ now += seconds+ for (const [key, expiry] of expiresAt) {+ if (expiry <= now) {+ store.delete(key)+ expiresAt.delete(key)+ }+ }+ },get: (key) => guard(store.get(key) ?? null),- set: (key, value) => {+ set: (key, value, ...options) => {store.set(key, value)+ if (options[0] === 'EX') {+ refresh([key], Number(options[1]))+ }return guard('OK')},del: async (...keys) => keys.filter((key) => store.delete(key)).length,@@ -34,17 +56,30 @@ export function makeGuidanceRedis(failing = false): GuidanceRedisStub {ttl: () => guard(-1),eval: (_script, _numberOfKeys, ...args) => {evalCalls.push(args)- const [matchedKey, suppressedKey, shownKey, _ttl, threshold, maxPerSession, mode, canFire] =+ const [matchedKey, suppressedKey, shownKey, ttlArg, threshold, maxPerSession, mode, canFire] =args.map(String)+ const ttl = Number(ttlArg)+ const keys = [matchedKey, suppressedKey, shownKey]if (mode === 'suppress') {store.set(suppressedKey!, '1')+ refresh(keys, ttl)return guard(0)}const matched = incr(matchedKey!)+ if (mode === 'mirror') {+ if (canFire === '1') {+ incr(shownKey!)+ }+ refresh(keys, ttl)+ return guard(0)+ }if (canFire !== '1' || matched < Number(threshold)) {+ refresh(keys, ttl)return guard(0)}- if (incr(shownKey!) > Number(maxPerSession)) {+ const shown = incr(shownKey!)+ refresh(keys, ttl)+ if (shown > Number(maxPerSession)) {return guard(0)}return guard(store.has(suppressedKey!) ? 2 : 1)