feat: unified notification system with GC tracking

- Add GCStats type and gcPending state to track deduplication activity
- Accumulate GC stats during fetch when runStrategies prunes duplicates
- Rewrite notification system to combine AI analysis and GC in one display
- Show GC-only notifications when AI prunes nothing but deduplication occurred
- Track totalGCTokens in session stats for lifetime GC contribution
- Display format: '🧹 DCP: ~20K saved (10 tools, ♻️ ~500) │ Session: ...'
- GC-only format: '♻️ DCP: ~500 collected │ Session: ...'

Author: Tarquinen

lib/core/janitor.ts

@@ -8,17 +8,19 @@ import { estimateTokensBatch, formatTokenCount } from "../tokenizer"
 import { saveSessionState } from "../state/persistence"
 import { ensureSessionRestored } from "../state"
 import {
-    sendPruningSummary,
+    sendUnifiedNotification,
     type NotificationContext
 } from "../ui/notification"
 
-// ============================================================================
-// Types
-// ============================================================================
-
 export interface SessionStats {
     totalToolsPruned: number
     totalTokensSaved: number
+    totalGCTokens: number
+}
+
+export interface GCStats {
+    tokensCollected: number
+    toolsDeduped: number
 }
 
 export interface PruningResult {
@@ -136,7 +138,11 @@ async function runWithStrategies(
         const alreadyPrunedIds = state.prunedIds.get(sessionID) ?? []
         const unprunedToolCallIds = toolCallIds.filter(id => !alreadyPrunedIds.includes(id))
 
-        if (unprunedToolCallIds.length === 0) {
+        // Get pending GC stats (accumulated since last notification)
+        const gcPending = state.gcPending.get(sessionID) ?? null
+
+        // If nothing to analyze and no GC activity, exit early
+        if (unprunedToolCallIds.length === 0 && !gcPending) {
             return null
         }
 
@@ -148,7 +154,7 @@ async function runWithStrategies(
         // PHASE 1: LLM ANALYSIS
         let llmPrunedIds: string[] = []
 
-        if (strategies.includes('ai-analysis')) {
+        if (strategies.includes('ai-analysis') && unprunedToolCallIds.length > 0) {
             llmPrunedIds = await runLlmAnalysis(
                 ctx,
                 sessionID,
@@ -161,33 +167,62 @@ async function runWithStrategies(
             )
         }
 
-        if (llmPrunedIds.length === 0) {
+        const finalNewlyPrunedIds = llmPrunedIds.filter(id => !alreadyPrunedIds.includes(id))
+
+        // If AI pruned nothing and no GC activity, nothing to report
+        if (finalNewlyPrunedIds.length === 0 && !gcPending) {
             return null
         }
 
-        const finalNewlyPrunedIds = llmPrunedIds.filter(id => !alreadyPrunedIds.includes(id))
-
         // PHASE 2: CALCULATE STATS & NOTIFICATION
         const tokensSaved = await calculateTokensSaved(finalNewlyPrunedIds, toolOutputs)
 
-        const currentStats = state.stats.get(sessionID) ?? { totalToolsPruned: 0, totalTokensSaved: 0 }
+        // Get current session stats, initializing with proper defaults
+        const currentStats = state.stats.get(sessionID) ?? {
+            totalToolsPruned: 0,
+            totalTokensSaved: 0,
+            totalGCTokens: 0
+        }
+
+        // Update session stats including GC contribution
         const sessionStats: SessionStats = {
             totalToolsPruned: currentStats.totalToolsPruned + finalNewlyPrunedIds.length,
-            totalTokensSaved: currentStats.totalTokensSaved + tokensSaved
+            totalTokensSaved: currentStats.totalTokensSaved + tokensSaved,
+            totalGCTokens: currentStats.totalGCTokens + (gcPending?.tokensCollected ?? 0)
         }
         state.stats.set(sessionID, sessionStats)
 
-        await sendPruningSummary(
+        // Send unified notification (handles all scenarios)
+        const notificationSent = await sendUnifiedNotification(
             ctx.notificationCtx,
             sessionID,
-            llmPrunedIds,
-            toolMetadata,
-            tokensSaved,
-            sessionStats,
+            {
+                aiPrunedCount: llmPrunedIds.length,
+                aiTokensSaved: tokensSaved,
+                aiPrunedIds: llmPrunedIds,
+                toolMetadata,
+                gcPending,
+                sessionStats
+            },
             currentAgent
         )
 
-        // PHASE 3: STATE UPDATE
+        // Clear pending GC stats after notification (whether sent or not - we've consumed them)
+        if (gcPending) {
+            state.gcPending.delete(sessionID)
+        }
+
+        // If we only had GC activity (no AI pruning), return null but notification was sent
+        if (finalNewlyPrunedIds.length === 0) {
+            if (notificationSent) {
+                logger.info("janitor", `GC-only notification: ~${formatTokenCount(gcPending?.tokensCollected ?? 0)} tokens from ${gcPending?.toolsDeduped ?? 0} deduped tools`, {
+                    trigger: options.trigger
+                })
+            }
+            return null
+        }
+
+        // PHASE 3: STATE UPDATE (only if AI pruned something)
         const allPrunedIds = [...new Set([...alreadyPrunedIds, ...llmPrunedIds])]
         state.prunedIds.set(sessionID, allPrunedIds)
 
@@ -203,6 +238,10 @@ async function runWithStrategies(
         if (options.reason) {
             logMeta.reason = options.reason
         }
+        if (gcPending) {
+            logMeta.gcTokens = gcPending.tokensCollected
+            logMeta.gcTools = gcPending.toolsDeduped
+        }
 
         logger.info("janitor", `Pruned ${prunedCount}/${candidateCount} tools, ${keptCount} kept (~${formatTokenCount(tokensSaved)} tokens)`, logMeta)
 

lib/fetch-wrapper/gc-tracker.ts

@@ -0,0 +1,77 @@
+import type { PluginState } from "../state"
+import type { Logger } from "../logger"
+
+export function accumulateGCStats(
+    state: PluginState,
+    sessionId: string,
+    prunedIds: string[],
+    body: any,
+    logger: Logger
+): void {
+    if (prunedIds.length === 0) return
+
+    const toolOutputs = extractToolOutputsFromBody(body, prunedIds)
+    const tokensCollected = estimateTokensFromOutputs(toolOutputs)
+
+    const existing = state.gcPending.get(sessionId) ?? { tokensCollected: 0, toolsDeduped: 0 }
+    
+    state.gcPending.set(sessionId, {
+        tokensCollected: existing.tokensCollected + tokensCollected,
+        toolsDeduped: existing.toolsDeduped + prunedIds.length
+    })
+
+    logger.debug("gc-tracker", "Accumulated GC stats", {
+        sessionId: sessionId.substring(0, 8),
+        newlyDeduped: prunedIds.length,
+        tokensThisCycle: tokensCollected,
+        pendingTotal: state.gcPending.get(sessionId)
+    })
+}
+
+function extractToolOutputsFromBody(body: any, prunedIds: string[]): string[] {
+    const outputs: string[] = []
+    const prunedIdSet = new Set(prunedIds.map(id => id.toLowerCase()))
+
+    // OpenAI Chat format
+    if (body.messages && Array.isArray(body.messages)) {
+        for (const m of body.messages) {
+            if (m.role === 'tool' && m.tool_call_id && prunedIdSet.has(m.tool_call_id.toLowerCase())) {
+                if (typeof m.content === 'string') {
+                    outputs.push(m.content)
+                }
+            }
+            // Anthropic format
+            if (m.role === 'user' && Array.isArray(m.content)) {
+                for (const part of m.content) {
+                    if (part.type === 'tool_result' && part.tool_use_id && prunedIdSet.has(part.tool_use_id.toLowerCase())) {
+                        if (typeof part.content === 'string') {
+                            outputs.push(part.content)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // OpenAI Responses format
+    if (body.input && Array.isArray(body.input)) {
+        for (const item of body.input) {
+            if (item.type === 'function_call_output' && item.call_id && prunedIdSet.has(item.call_id.toLowerCase())) {
+                if (typeof item.output === 'string') {
+                    outputs.push(item.output)
+                }
+            }
+        }
+    }
+
+    return outputs
+}
+
+// Character-based approximation (chars / 4) to avoid async tokenizer in fetch path
+function estimateTokensFromOutputs(outputs: string[]): number {
+    let totalChars = 0
+    for (const output of outputs) {
+        totalChars += output.length
+    }
+    return Math.round(totalChars / 4)
+}

lib/fetch-wrapper/index.ts

@@ -7,6 +7,7 @@ import { handleOpenAIChatAndAnthropic } from "./openai-chat"
 import { handleGemini } from "./gemini"
 import { handleOpenAIResponses } from "./openai-responses"
 import { runStrategies } from "../core/strategies"
+import { accumulateGCStats } from "./gc-tracker"
 
 export type { FetchHandlerContext, FetchHandlerResult, SynthPrompts } from "./types"
 
@@ -96,6 +97,9 @@ export function installFetchWrapper(
                             // Normalize to lowercase to match janitor's ID normalization
                             const normalizedIds = result.prunedIds.map(id => id.toLowerCase())
                             state.prunedIds.set(sessionId, [...new Set([...alreadyPruned, ...normalizedIds])])
+
+                            // Track GC activity for the next notification
+                            accumulateGCStats(state, sessionId, result.prunedIds, body, logger)
                         }
                     }
                 }

lib/state/index.ts

@@ -1,32 +1,17 @@
-import type { SessionStats } from "../core/janitor"
+import type { SessionStats, GCStats } from "../core/janitor"
 import type { Logger } from "../logger"
 import { loadSessionState } from "./persistence"
 
-/**
- * Centralized state management for the DCP plugin.
- * All mutable state is stored here and shared across modules.
- */
 export interface PluginState {
-    /** Map of session IDs to arrays of pruned tool call IDs */
     prunedIds: Map<string, string[]>
-    /** Map of session IDs to session statistics */
     stats: Map<string, SessionStats>
-    /** Cache of tool call IDs to their parameters */
+    gcPending: Map<string, GCStats>
     toolParameters: Map<string, ToolParameterEntry>
-    /** Cache of session IDs to their model info */
     model: Map<string, ModelInfo>
-    /** 
-     * Maps Google/Gemini tool positions to OpenCode tool call IDs for correlation.
-     * Key: sessionID, Value: Map<positionKey, toolCallId> where positionKey is "toolName:index"
-     */
     googleToolCallMapping: Map<string, Map<string, string>>
-    /** Set of session IDs that have been restored from disk */
     restoredSessions: Set<string>
-    /** Set of session IDs we've already checked for subagent status (to avoid redundant API calls) */
     checkedSessions: Set<string>
-    /** Set of session IDs that are subagents (have a parentID) - used to skip fetch wrapper processing */
     subagentSessions: Set<string>
-    /** The most recent session ID seen in chat.params - used to correlate fetch requests */
     lastSeenSessionId: string | null
 }
 
@@ -40,13 +25,11 @@ export interface ModelInfo {
     modelID: string
 }
 
-/**
- * Creates a fresh plugin state instance.
- */
 export function createPluginState(): PluginState {
     return {
         prunedIds: new Map(),
         stats: new Map(),
+        gcPending: new Map(),
         toolParameters: new Map(),
         model: new Map(),
         googleToolCallMapping: new Map(),
@@ -78,7 +61,12 @@ export async function ensureSessionRestored(
             })
         }
         if (!state.stats.has(sessionId)) {
-            state.stats.set(sessionId, persisted.stats)
+            const stats: SessionStats = {
+                totalToolsPruned: persisted.stats.totalToolsPruned,
+                totalTokensSaved: persisted.stats.totalTokensSaved,
+                totalGCTokens: persisted.stats.totalGCTokens ?? 0
+            }
+            state.stats.set(sessionId, stats)
         }
     }
 }