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.

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.ts
index 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 * 60
const 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
+end
if ARGV[5] ~= '1' or matched < tonumber(ARGV[2]) then
return 0
end
@@ -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 | undefined
for (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.ts
index 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.ts
index 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)