feat: nudgeGrowthTokens — token-based Tips gating (default 6K)

Author: ranxianglei

dcp.schema.json

@@ -275,6 +275,11 @@
                     "default": 4000,
                     "minimum": 1,
                     "description": "Hard limit for summary length in characters"
+                },
+                "nudgeGrowthTokens": {
+                    "type": "number",
+                    "default": 6000,
+                    "description": "Token growth required between per-message nudges (absolute, not percentage). Shows Tips only after context grows by this many tokens."
                 }
             },
             "default": {
@@ -291,7 +296,8 @@
                 "protectTags": false,
                 "protectUserMessages": false,
                 "minNudgeContextPercent": 15,
-                "maxSummaryLengthHard": 3000
+                "maxSummaryLengthHard": 3000,
+                "nudgeGrowthTokens": 6000
             }
         },
         "gc": {
@@ -431,4 +437,4 @@
             }
         }
     }
-}
+}

lib/config-validation.ts

@@ -35,6 +35,7 @@ export const VALID_CONFIG_KEYS = new Set([
     "compress.modelMinLimits",
     "compress.nudgeFrequency",
     "compress.minNudgeContextPercent",
+    "compress.nudgeGrowthTokens",
     "compress.iterationNudgeThreshold",
     "compress.nudgeForce",
     "compress.protectedTools",

lib/config.ts

@@ -25,6 +25,7 @@ export interface CompressConfig {
     modelMinLimits?: Record<string, number | `${number}%`>
     nudgeFrequency: number
     minNudgeContextPercent: number
+    nudgeGrowthTokens: number
     iterationNudgeThreshold: number
     nudgeForce: "strong" | "soft"
     protectedTools: string[]
@@ -191,6 +192,7 @@ const defaultConfig: PluginConfig = {
         minContextLimit: "45%",
         nudgeFrequency: 5,
         minNudgeContextPercent: 15,
+        nudgeGrowthTokens: 6000,
         iterationNudgeThreshold: 15,
         nudgeForce: "soft",
         protectedTools: [...COMPRESS_DEFAULT_PROTECTED_TOOLS],
@@ -400,6 +402,7 @@ function mergeCompress(
         modelMinLimits: override.modelMinLimits ?? base.modelMinLimits,
         nudgeFrequency: override.nudgeFrequency ?? base.nudgeFrequency,
         minNudgeContextPercent: override.minNudgeContextPercent ?? base.minNudgeContextPercent,
+        nudgeGrowthTokens: override.nudgeGrowthTokens ?? base.nudgeGrowthTokens,
         iterationNudgeThreshold: override.iterationNudgeThreshold ?? base.iterationNudgeThreshold,
         nudgeForce: override.nudgeForce ?? base.nudgeForce,
         protectedTools: [...new Set([...base.protectedTools, ...(override.protectedTools ?? [])])],

lib/messages/inject/inject.ts

@@ -167,31 +167,25 @@ export const injectCompressNudges = (
 
     const contextPct = modelContextLimit && currentTokens ? (currentTokens / modelContextLimit) * 100 : 0
     const minPercent = config.compress?.minNudgeContextPercent ?? 15
+    const growthTokens = config.compress?.nudgeGrowthTokens ?? 6000
+    const lastNudgeTokens = state.nudges.lastPerMessageNudgeTokens ?? 0
+    const growthSinceLastNudge = (currentTokens ?? 0) - lastNudgeTokens
+    const shouldNudge = lastNudgeTokens === 0 || growthSinceLastNudge >= growthTokens
 
     injectContextUsage(suffixMessage, config, currentTokens, modelContextLimit)
 
-    // Determine tips tier: light (every turn) vs warning (key nodes only)
     let tipsText: string | null = null
 
-    if (overMaxLimit || overMinLimit) {
-        // Warning zone: show at key nodes only (first crossing or 10pp growth)
-        const lastWarnPct = state.nudges.lastPerMessageNudgeTokens && modelContextLimit
-            ? (state.nudges.lastPerMessageNudgeTokens / modelContextLimit) * 100
-            : 0
-        const growthSinceWarn = contextPct - lastWarnPct
-        if (lastWarnPct === 0 || growthSinceWarn >= 10) {
-            tipsText = overMaxLimit
-                ? "\n\n⚠️ Context limit reached — compress now. Prioritize consumed tool outputs.\n\n{ \"topic\": \"...\", \"content\": [{ \"startId\": \"<ID>\", \"endId\": \"<ID>\", \"summary\": \"...\" }] }\n\nOnly use IDs from visible messages above. Compress older work first."
-                : "\n\n⚠️ Context is growing — consider compressing older work. Tools: compress, decompress, search_context."
-            state.nudges.lastPerMessageNudgeTokens = currentTokens ?? 0
-            state.nudges.lastPerMessageNudgeTurn = state.currentTurn ?? 0
-        }
-    } else if (contextPct >= minPercent) {
-        tipsText = "\n\n💡 Tools: compress, decompress, search_context."
-        // Reset warning tracking when context drops below warning zone
-        if (state.nudges.lastPerMessageNudgeTokens) {
-            state.nudges.lastPerMessageNudgeTokens = 0
+    if (contextPct >= minPercent && shouldNudge) {
+        if (overMaxLimit) {
+            tipsText = "\n\n⚠️ Context limit reached — compress now. Prioritize consumed tool outputs.\n\n{ \"topic\": \"...\", \"content\": [{ \"startId\": \"<ID>\", \"endId\": \"<ID>\", \"summary\": \"...\" }] }\n\nOnly use IDs from visible messages above. Compress older work first."
+        } else if (overMinLimit) {
+            tipsText = "\n\n⚠️ Context is growing — consider compressing older work. Tools: compress, decompress, search_context."
+        } else {
+            tipsText = "\n\n💡 Tools: compress, decompress, search_context."
         }
+        state.nudges.lastPerMessageNudgeTokens = currentTokens ?? 0
+        state.nudges.lastPerMessageNudgeTurn = state.currentTurn ?? 0
     }
 
     if (config.compress.mode !== "message") {