feat(plugin): configurable commit cluster trigger + heuristic gate fix + dashboard improvements

ualtinok · ualtinok · commit c0d5f8115802 · 2026-04-01T18:08:44.000+02:00
- Add commit_cluster_trigger config (enabled: true, min_clusters: 3 by default)
  allowing users to tune or disable commit-cluster based historian triggering
- Fix heuristics blocked when ctx_reduce_enabled=false (no pending ops meant
  tool cleanup and reasoning clearing never ran on execute passes)
- Update heuristic log message from misleading 'pending_ops_execute' to 'scheduler_execute'
- Fix dashboard cache diagnostics labeling old events as 'First message (new session)'
  by checking whether earlier assistant messages exist in the DB
- Add commit cluster trigger toggle + min clusters input to dashboard config editor
- Document commit_cluster_trigger in CONFIGURATION.md with explanation of what
  commit clusters are
diff --git a/CONFIGURATION.md b/CONFIGURATION.md
@@ -49,6 +49,27 @@ Higher-tier models with longer cache windows benefit from a longer TTL. Setting
 | `compartment_token_budget` | `number` | `20000` | Token budget for historian input chunks. |
 | `historian_timeout_ms` | `number` | `300000` | Timeout per historian call (ms). |
 | `history_budget_percentage` | `number` (0–1) | `0.15` | Fraction of usable context reserved for the history block. Triggers compression when exceeded. |
+| `commit_cluster_trigger` | `object` | See below | Controls the commit-cluster historian trigger. |
+
+### `commit_cluster_trigger`
+
+A **commit cluster** is a distinct work phase where the agent made one or more git commits, separated from other commit clusters by meaningful user turns. For example, if the agent commits a fix, then the user asks a new question, and the agent commits another change — that's 2 commit clusters. This heuristic detects natural work-unit boundaries and fires historian to compartmentalize them, even when context pressure is low.
+
+```jsonc
+{
+  "commit_cluster_trigger": {
+    "enabled": true,    // default: true
+    "min_clusters": 3   // default: 3, minimum: 1
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable commit-cluster based historian triggering. |
+| `min_clusters` | `number` | `3` | Minimum number of commit clusters in the unsummarized tail before historian fires. The tail must also contain at least `compartment_token_budget` tokens. |
+
+Set `enabled: false` to disable this trigger entirely and rely only on pressure-based and tail-size triggers for historian.
 
 ---
 
diff --git a/packages/dashboard/src-tauri/src/db.rs b/packages/dashboard/src-tauri/src/db.rs
@@ -552,6 +552,41 @@ fn load_raw_db_cache_events(limit: usize, since_timestamp: Option<i64>) -> Resul
 
 fn build_db_cache_events(rows: Vec<RawDbCacheEvent>, enrich_causes: bool) -> Vec<DbCacheEvent> {
     let log_cause_candidates = if enrich_causes { build_log_cause_candidates() } else { Vec::new() };
+
+    // Build a map of earliest timestamp per session in our window so we can
+    // detect whether an event is truly the session's first message vs just
+    // the oldest event in the current 200-event window.
+    let mut earliest_ts_in_window: HashMap<String, i64> = HashMap::new();
+    for row in &rows {
+        earliest_ts_in_window
+            .entry(row.session_id.clone())
+            .and_modify(|ts| { if row.timestamp < *ts { *ts = row.timestamp; } })
+            .or_insert(row.timestamp);
+    }
+
+    // Check which sessions truly have their first-ever assistant message in our window
+    // by querying whether an earlier assistant message exists in the DB.
+    let true_first_sessions: HashSet<String> = if let Some(opencode_db_path) = resolve_opencode_db_path() {
+        if let Ok(conn) = open_readonly(&opencode_db_path) {
+            earliest_ts_in_window.iter().filter(|(session_id, &earliest_ts)| {
+                // If there's any assistant message with tokens BEFORE our earliest, it's not the first
+                let has_earlier: bool = conn.query_row(
+                    "SELECT EXISTS(SELECT 1 FROM message WHERE session_id = ?1
+                     AND json_extract(data, '$.role') = 'assistant'
+                     AND COALESCE(CAST(json_extract(data, '$.tokens.total') AS INTEGER), 0) > 0
+                     AND time_created < ?2)",
+                    rusqlite::params![session_id, earliest_ts],
+                    |row| row.get(0),
+                ).unwrap_or(false);
+                !has_earlier
+            }).map(|(sid, _)| sid.clone()).collect()
+        } else {
+            HashSet::new()
+        }
+    } else {
+        HashSet::new()
+    };
+
     let mut seen_sessions = HashSet::new();
     let mut chronological = Vec::with_capacity(rows.len());
 
@@ -564,7 +599,8 @@ fn build_db_cache_events(rows: Vec<RawDbCacheEvent>, enrich_causes: bool) -> Vec
         };
 
         let is_first_session_event = seen_sessions.insert(row.session_id.clone());
-        let (severity, cause) = if is_first_session_event {
+        let is_truly_first = is_first_session_event && true_first_sessions.contains(&row.session_id);
+        let (severity, cause) = if is_truly_first {
             (
                 "info".to_string(),
                 Some("First message (new session)".to_string()),
diff --git a/packages/dashboard/src/components/ConfigEditor/ConfigEditor.tsx b/packages/dashboard/src/components/ConfigEditor/ConfigEditor.tsx
@@ -512,6 +512,53 @@ function ConfigForm(props: {
                       {/* Right: Settings sliders */}
                       <div class="config-card-content">
                         <For each={fields}>{renderField}</For>
+
+                        {/* Commit Cluster Trigger */}
+                        {(() => {
+                          const commitCluster = () => (getNestedValue(formData(), "commit_cluster_trigger") as { enabled?: boolean; min_clusters?: number } | undefined) ?? {};
+                          const enabled = () => commitCluster().enabled ?? true;
+                          const minClusters = () => commitCluster().min_clusters ?? 3;
+                          return (
+                            <>
+                              <div class="config-field">
+                                <div class="config-field-header">
+                                  <label class="config-field-label">Commit Cluster Trigger</label>
+                                  <span class="config-field-key">commit_cluster_trigger.enabled</span>
+                                </div>
+                                <span class="config-field-desc">Fire historian when enough git commit clusters accumulate in the unsummarized conversation tail. A commit cluster is a distinct work phase where the agent made git commits, separated by meaningful user turns.</span>
+                                <label class="toggle-switch">
+                                  <input
+                                    type="checkbox"
+                                    checked={enabled()}
+                                    onChange={(e) => handleFieldChange("commit_cluster_trigger", { ...commitCluster(), enabled: e.currentTarget.checked })}
+                                  />
+                                  <span class="toggle-slider" />
+                                  <span class="toggle-label">{enabled() ? "Enabled" : "Disabled"}</span>
+                                </label>
+                              </div>
+
+                              <Show when={enabled()}>
+                                <div class="config-field">
+                                  <div class="config-field-header">
+                                    <label class="config-field-label">Min Clusters</label>
+                                    <span class="config-field-key">commit_cluster_trigger.min_clusters</span>
+                                  </div>
+                                  <span class="config-field-desc">Minimum number of commit clusters required to trigger historian</span>
+                                  <input
+                                    class="config-input"
+                                    type="number"
+                                    min={1}
+                                    value={minClusters()}
+                                    onInput={(e) => {
+                                      const v = e.currentTarget.value;
+                                      handleFieldChange("commit_cluster_trigger", { ...commitCluster(), min_clusters: v ? Math.max(1, Number(v)) : 3 });
+                                    }}
+                                  />
+                                </div>
+                              </Show>
+                            </>
+                          );
+                        })()}
                       </div>
                     </div>
                   ) : (
diff --git a/packages/plugin/src/config/schema/magic-context.test.ts b/packages/plugin/src/config/schema/magic-context.test.ts
@@ -58,6 +58,10 @@ describe("MagicContextConfigSchema", () => {
                 compartment_token_budget: 25_000,
                 history_budget_percentage: 0.2,
                 historian_timeout_ms: 360_000,
+                commit_cluster_trigger: {
+                    enabled: true,
+                    min_clusters: 3,
+                },
                 embedding: {
                     provider: "openai-compatible",
                     endpoint: "http://localhost:1234/v1",
diff --git a/packages/plugin/src/config/schema/magic-context.ts b/packages/plugin/src/config/schema/magic-context.ts
@@ -120,6 +120,10 @@ export interface MagicContextConfig {
     compartment_token_budget: number;
     history_budget_percentage: number;
     historian_timeout_ms: number;
+    commit_cluster_trigger: {
+        enabled: boolean;
+        min_clusters: number;
+    };
     embedding: EmbeddingConfig;
     memory: {
         enabled: boolean;
@@ -175,6 +179,15 @@ export const MagicContextConfigSchema = z
             .default(DEFAULT_HISTORY_BUDGET_PERCENTAGE),
         /** Timeout for each historian prompt call in milliseconds (default: 300000) */
         historian_timeout_ms: z.number().min(60_000).default(DEFAULT_HISTORIAN_TIMEOUT_MS),
+        /** Commit-cluster trigger: fire historian when enough commit clusters accumulate in the unsummarized tail */
+        commit_cluster_trigger: z
+            .object({
+                /** Enable commit-cluster based historian triggering (default: true) */
+                enabled: z.boolean().default(true),
+                /** Minimum commit clusters required to trigger historian (min: 1, default: 3) */
+                min_clusters: z.number().min(1).default(3),
+            })
+            .default({ enabled: true, min_clusters: 3 }),
         /** Embedding provider configuration */
         embedding: EmbeddingConfigSchema.default({
             provider: "local",
diff --git a/packages/plugin/src/hooks/magic-context/command-handler.ts b/packages/plugin/src/hooks/magic-context/command-handler.ts
@@ -183,6 +183,7 @@ export function createMagicContextCommandHandler(deps: {
     nudgeIntervalTokens?: number;
     executeThresholdPercentage?: number | { default: number; [modelKey: string]: number };
     historyBudgetPercentage?: number;
+    commitClusterTrigger?: { enabled: boolean; min_clusters: number };
     getLiveModelKey?: (sessionId: string) => string | undefined;
     onFlush?: (sessionId: string) => void;
     executeRecomp?: (sessionId: string) => Promise<string>;
@@ -255,6 +256,7 @@ export function createMagicContextCommandHandler(deps: {
                     deps.executeThresholdPercentage,
                     liveModelKey,
                     deps.historyBudgetPercentage,
+                    deps.commitClusterTrigger,
                 );
                 result += result ? `\n\n${statusOutput}` : statusOutput;
             }
diff --git a/packages/plugin/src/hooks/magic-context/compartment-trigger.ts b/packages/plugin/src/hooks/magic-context/compartment-trigger.ts
@@ -15,7 +15,7 @@ const PROACTIVE_TRIGGER_OFFSET_PERCENTAGE = 2;
 const POST_DROP_TARGET_RATIO = 0.75;
 const MIN_PROACTIVE_TAIL_TOKEN_ESTIMATE = 6_000;
 const MIN_PROACTIVE_TAIL_MESSAGE_COUNT = 12;
-const MIN_COMMIT_CLUSTERS_FOR_TRIGGER = 2;
+const DEFAULT_MIN_COMMIT_CLUSTERS_FOR_TRIGGER = 3;
 const TAIL_SIZE_TRIGGER_MULTIPLIER = 3;
 const FORCE_COMPARTMENT_PERCENTAGE = 80;
 const BLOCK_UNTIL_DONE_PERCENTAGE = 95;
@@ -182,6 +182,7 @@ export function checkCompartmentTrigger(
     autoDropToolAge?: number,
     protectedTagCount?: number,
     clearReasoningAge?: number,
+    commitClusterTrigger?: { enabled: boolean; min_clusters: number },
 ): CompartmentTriggerResult {
     if (sessionMeta.compartmentInProgress) {
         return { shouldFire: false };
@@ -223,14 +224,18 @@ export function checkCompartmentTrigger(
         return { shouldFire: true, reason: "force_80" };
     }
 
-    // Commit-cluster trigger: 2+ distinct work phases with commits, enough token volume
+    // Commit-cluster trigger: N+ distinct work phases with commits, enough token volume
+    const clusterEnabled = commitClusterTrigger?.enabled ?? true;
+    const minClusters =
+        commitClusterTrigger?.min_clusters ?? DEFAULT_MIN_COMMIT_CLUSTERS_FOR_TRIGGER;
     if (
-        tailInfo.commitClusterCount >= MIN_COMMIT_CLUSTERS_FOR_TRIGGER &&
+        clusterEnabled &&
+        tailInfo.commitClusterCount >= minClusters &&
         tailInfo.tokenEstimate >= compartmentTokenBudget
     ) {
         sessionLog(
             sessionId,
-            `compartment trigger: commit-cluster fire — ${tailInfo.commitClusterCount} clusters, ~${tailInfo.tokenEstimate} tokens in eligible prefix`,
+            `compartment trigger: commit-cluster fire — ${tailInfo.commitClusterCount} clusters (min=${minClusters}), ~${tailInfo.tokenEstimate} tokens in eligible prefix`,
         );
         return { shouldFire: true, reason: "commit_clusters" };
     }
diff --git a/packages/plugin/src/hooks/magic-context/event-handler.ts b/packages/plugin/src/hooks/magic-context/event-handler.ts
@@ -62,6 +62,7 @@ export interface EventHandlerDeps {
         execute_threshold_percentage?: number | { default: number; [modelKey: string]: number };
         cache_ttl: CacheTtlConfig;
         modelContextLimitsCache?: Map<string, number>;
+        commit_cluster_trigger?: { enabled: boolean; min_clusters: number };
     };
     tagger: Tagger;
     db: ReturnType<typeof import("../../features/magic-context/storage").openDatabase>;
@@ -292,6 +293,7 @@ export function createEventHandler(deps: EventHandlerDeps) {
                             deps.config.auto_drop_tool_age ?? 100,
                             deps.config.protected_tags,
                             deps.config.clear_reasoning_age ?? 50,
+                            deps.config.commit_cluster_trigger,
                         );
 
                         if (triggerResult.shouldFire) {
diff --git a/packages/plugin/src/hooks/magic-context/execute-status.ts b/packages/plugin/src/hooks/magic-context/execute-status.ts
@@ -33,6 +33,7 @@ export function executeStatus(
         | { default: number; [modelKey: string]: number } = DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE,
     liveModelKey?: string,
     historyBudgetPercentage?: number,
+    commitClusterTrigger?: { enabled: boolean; min_clusters: number },
 ): string {
     const executeThresholdPercentage = resolveExecuteThreshold(
         executeThresholdPercentageConfig,
@@ -123,7 +124,7 @@ export function executeStatus(
                 `- Resolved context limit: ${contextLimit > 0 ? contextLimit.toLocaleString() : "unknown"}`,
                 `- Proactive compartment evaluation: ${proactiveCompartmentTrigger}%`,
                 `- Post-drop target for historian: ${(executeThresholdPercentage * POST_DROP_TARGET_RATIO).toFixed(0)}% (${executeThresholdPercentage}% * ${POST_DROP_TARGET_RATIO})`,
-                `- Historian also fires on: 2+ commit clusters with sufficient tokens, or tail > ${3}x compartment budget`,
+                `- Commit cluster trigger: ${commitClusterTrigger?.enabled !== false ? `enabled (min ${commitClusterTrigger?.min_clusters ?? 3} clusters)` : "disabled"}, tail-size trigger: > 3x compartment budget`,
             );
         }
 
diff --git a/packages/plugin/src/hooks/magic-context/hook.ts b/packages/plugin/src/hooks/magic-context/hook.ts
@@ -75,6 +75,7 @@ export interface MagicContextDeps {
         };
         sidekick?: SidekickConfig;
         dreamer?: DreamerConfig;
+        commit_cluster_trigger?: { enabled: boolean; min_clusters: number };
     };
 }
 
@@ -242,6 +243,7 @@ export function createMagicContextHook(deps: MagicContextDeps) {
         nudgeIntervalTokens: deps.config.nudge_interval_tokens ?? DEFAULT_NUDGE_INTERVAL_TOKENS,
         executeThresholdPercentage: deps.config.execute_threshold_percentage ?? 65,
         historyBudgetPercentage: deps.config.history_budget_percentage,
+        commitClusterTrigger: deps.config.commit_cluster_trigger,
         getLiveModelKey: (sessionId) => {
             const model = liveModelBySession.get(sessionId);
             return model ? `${model.providerID}/${model.modelID}` : undefined;
diff --git a/packages/plugin/src/hooks/magic-context/transform-postprocess-phase.ts b/packages/plugin/src/hooks/magic-context/transform-postprocess-phase.ts
@@ -118,7 +118,7 @@ export function runPostTransformPhase(args: RunPostTransformPhaseArgs): void {
             ? "explicit_flush"
             : forceMaterialization
               ? `force_materialization (${args.contextUsage.percentage.toFixed(1)}% >= ${args.forceMaterializationPercentage}%)`
-              : `pending_ops_execute (pendingOps=${pendingOps.length}, scheduler=${args.schedulerDecision})`;
+              : `scheduler_execute (pendingOps=${pendingOps.length}, scheduler=${args.schedulerDecision})`;
         sessionLog(
             args.sessionId,
             `heuristics WILL RUN — reason=${reason}, context=${args.contextUsage.percentage.toFixed(1)}%, turn=${args.currentTurnId}`,
