@monotykamary/pi-vcc 0.3.16

package/src/hooks/before-compact.ts

@@ -0,0 +1,564 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { writeFileSync } from "fs";
+import { compile, type CompileInput } from "../core/summarize";
+import { loadSettings, getModelThreshold, resolveReserveTokens, type PiVccSettings } from "../core/settings";
+import { isProactiveTriggerActive } from "./proactive-threshold";
+import { triggerInvisibleContinue } from "../core/invisible-continue";
+import type { PiVccCompactionDetails } from "../details";
+
+export const PI_VCC_COMPACT_INSTRUCTION = "__pi_vcc__";
+
+export interface CompactionStats {
+  summarized: number;
+  kept: number;
+  keptTokensEst: number;
+}
+
+let lastStats: CompactionStats | null = null;
+let lastCompactWasPiVcc = false;
+let lastCompactHandledByVcc = false;
+export const getLastCompactionStats = () => lastStats;
+
+const formatTokens = (n: number): string => {
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+};
+
+/**
+ * Compute the entry-ID range for summarized messages.
+ *
+ * Uses entry IDs instead of numeric indices so that vcc_recall can correctly
+ * resolve the range against the full session file (not just the active branch,
+ * where numeric indices would be branch-relative and wrong).
+ *
+ * Returns [firstSummarizedEntryId, lastSummarizedEntryId] or undefined.
+ */
+const computeMessageRange = (
+  branchEntries: any[],
+  firstKeptEntryId: string,
+): [string, string] | undefined => {
+  if (!firstKeptEntryId) return undefined;
+
+  // If compact-all sentinel, find the last message entry
+  if (firstKeptEntryId === "") {
+    let lastId: string | undefined;
+    for (const e of branchEntries) {
+      if (e.type === "message" && e.message && e.id) {
+        lastId = e.id;
+      }
+    }
+    return lastId ? [branchEntries.find((e: any) => e.type === "message" && e.message)?.id ?? "", lastId] as [string, string] : undefined;
+  }
+
+  // Find the first message entry (start of summarized range)
+  const firstMsgId = branchEntries.find(
+    (e: any) => e.type === "message" && e.message && e.id,
+  )?.id;
+  if (!firstMsgId) return undefined;
+
+  // If first kept entry IS the first message, nothing was summarized
+  if (firstMsgId === firstKeptEntryId) return undefined;
+
+  return [firstMsgId, firstKeptEntryId];
+};
+
+const dbg = (settings: PiVccSettings, data: Record<string, unknown>) => {
+  if (!settings.debug) return;
+  try { writeFileSync("/tmp/pi-vcc-debug.json", JSON.stringify(data, null, 2)); } catch {}
+};
+
+const previewContent = (content: unknown): string => {
+  if (typeof content === "string") return content.slice(0, 300);
+  if (Array.isArray(content)) {
+    return content
+      .map((c: any) => {
+        if (c?.type === "text") return c.text ?? "";
+        if (c?.type === "toolCall") return `[toolCall:${c.name}]`;
+        if (c?.type === "thinking") return `[thinking]`;
+        if (c?.type === "image") return `[image:${c.mimeType}]`;
+        return `[${c?.type ?? "unknown"}]`;
+      })
+      .join("\n")
+      .slice(0, 300);
+  }
+  return "";
+};
+
+interface EntryWithMessage {
+  entry: { id: string; type: string };
+  message: { role: string; content: unknown };
+}
+
+export type OwnCutCancelReason =
+  | "no_live_messages"
+  | "too_few_live_messages";
+
+export type OwnCutResult =
+  | { ok: true; messages: any[]; firstKeptEntryId: string; compactAll: boolean }
+  | { ok: false; reason: OwnCutCancelReason };
+
+/**
+ * Find a completed tool-call cycle boundary in the first half of the
+ * live messages. Used when there's only a single user message and we
+ * can't cut at a task boundary.
+ *
+ * Scans for completed assistant→toolResult cycles and returns the index
+ * of the last toolResult in the cycle nearest the midpoint.
+ */
+const findMidCycleBoundary = (liveMessages: EntryWithMessage[]): number => {
+  const cycles: number[] = []; // end indices (toolResult) of completed cycles
+  let currentAssistantIdx = -1;
+  const pendingCalls = new Set<string>();
+
+  for (let i = 0; i < liveMessages.length; i++) {
+    const msg = liveMessages[i].message;
+    if (msg.role === "user") continue;
+    if (msg.role === "assistant") {
+      currentAssistantIdx = i;
+      pendingCalls.clear();
+      const content = msg.content;
+      if (Array.isArray(content)) {
+        for (const part of content) {
+          if (part.type === "toolCall" && part.id) pendingCalls.add(part.id);
+        }
+      }
+      continue;
+    }
+    if (msg.role === "toolResult") {
+      const callId = (msg as any).toolCallId as string | undefined;
+      if (callId) pendingCalls.delete(callId);
+      if (pendingCalls.size === 0 && currentAssistantIdx >= 0) {
+        cycles.push(i);
+        currentAssistantIdx = -1;
+      }
+    }
+  }
+
+  if (cycles.length === 0) return -1;
+
+  // Pick the cycle nearest the midpoint of the first half
+  const targetIdx = Math.floor(liveMessages.length / 2);
+  let best = cycles[0];
+  let bestDist = Math.abs(cycles[0] - targetIdx);
+  for (let i = 1; i < cycles.length; i++) {
+    const dist = Math.abs(cycles[i] - targetIdx);
+    if (dist < bestDist) {
+      best = cycles[i];
+      bestDist = dist;
+    }
+  }
+  return best;
+};
+
+export function buildOwnCut(branchEntries: any[]): OwnCutResult {
+  // Find the last compaction entry and its firstKeptEntryId
+  let lastCompactionIdx = -1;
+  let lastKeptId: string | undefined;
+  for (let i = branchEntries.length - 1; i >= 0; i--) {
+    if (branchEntries[i].type === "compaction") {
+      lastCompactionIdx = i;
+      lastKeptId = branchEntries[i].firstKeptEntryId;
+      break;
+    }
+  }
+
+  // Orphan recovery: triggers when lastKeptId is set to "" (sentinel from prior
+  // compact-all) OR set to an id that no longer exists in the branch. In both cases,
+  // start collecting from right after the last compaction entry.
+  const hasPriorCompaction = lastCompactionIdx >= 0;
+  const hasValidKeptId = !!lastKeptId && branchEntries.some((e: any) => e.id === lastKeptId);
+  const orphanRecovery = hasPriorCompaction && !hasValidKeptId;
+
+  // Collect live messages
+  const liveMessages: EntryWithMessage[] = [];
+  if (orphanRecovery) {
+    for (let i = lastCompactionIdx + 1; i < branchEntries.length; i++) {
+      const e = branchEntries[i];
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) {
+        liveMessages.push({ entry: e, message: e.message });
+      }
+    }
+  } else {
+    let foundKept = !lastKeptId; // if no prior compaction, start collecting immediately
+    for (const e of branchEntries) {
+      if (!foundKept && e.id === lastKeptId) foundKept = true;
+      if (!foundKept) continue;
+      if (e.type === "compaction") continue;
+      if (e.type === "message" && e.message) {
+        liveMessages.push({ entry: e, message: e.message });
+      }
+    }
+  }
+
+  if (liveMessages.length === 0) return { ok: false, reason: "no_live_messages" };
+  if (liveMessages.length <= 2) return { ok: false, reason: "too_few_live_messages" };
+
+  // Task-boundary-aware cut: find the last user message whose response cycle
+  // is complete (no unmatched tool calls). If the turn is mid-flight, push the
+  // cut back to the previous user message to keep the entire in-progress turn
+  // in the tail.
+  let cutIdx = liveMessages.length - 1;
+  while (cutIdx > 0 && liveMessages[cutIdx].message.role !== "user") {
+    cutIdx--;
+  }
+
+  // Check if the turn following the last user message is "in progress"
+  // (has an unmatched toolCall — assistant started but didn't finish)
+  if (cutIdx > 0) {
+    const toolCallIds = new Set<string>();
+    const toolResultIds = new Set<string>();
+    for (let i = cutIdx + 1; i < liveMessages.length; i++) {
+      const msg = liveMessages[i].message;
+      if (msg.role === "user") break; // next turn starts
+      // toolResult messages carry toolCallId at the message level, not in content parts
+      if (msg.role === "toolResult" && (msg as any).toolCallId) {
+        toolResultIds.add((msg as any).toolCallId);
+        continue;
+      }
+      const content = msg.content;
+      if (typeof content === "string" || !Array.isArray(content)) continue;
+      for (const part of content) {
+        if (part.type === "toolCall" && part.id) toolCallIds.add(part.id);
+        if (part.type === "toolResult" && part.toolCallId) toolResultIds.add(part.toolCallId);
+      }
+    }
+    const hasUnmatchedToolCall = [...toolCallIds].some(id => !toolResultIds.has(id));
+    if (hasUnmatchedToolCall) {
+      // Push cut back to the previous user message
+      for (let i = cutIdx - 1; i > 0; i--) {
+        if (liveMessages[i].message.role === "user") {
+          cutIdx = i;
+          break;
+        }
+      }
+    }
+  }
+
+  if (cutIdx <= 0) {
+    // Single user prompt (or no user at all) with a long agentic chain.
+    // Instead of compact-all (which destroys the tail), find a completed
+    // tool-call cycle boundary in the first half and cut there. This
+    // preserves the later part of the session while summarizing the earlier
+    // tool-call cycles.
+    const cycleEndIdx = findMidCycleBoundary(liveMessages);
+    if (cycleEndIdx > 0 && cycleEndIdx < liveMessages.length - 1) {
+      return {
+        ok: true,
+        messages: liveMessages.slice(0, cycleEndIdx + 1).map((e) => e.message),
+        firstKeptEntryId: liveMessages[cycleEndIdx + 1].entry.id,
+        compactAll: false,
+      };
+    }
+    // No completed cycle boundary found — fall back to compact-all as last resort.
+    // firstKeptEntryId="" is a sentinel: pi-core's buildSessionContext won't match it
+    // (so 0 kept from pre-compaction), and next buildOwnCut triggers orphan recovery.
+    return {
+      ok: true,
+      messages: liveMessages.map((e) => e.message),
+      firstKeptEntryId: "",
+      compactAll: true,
+    };
+  }
+
+  return {
+    ok: true,
+    messages: liveMessages.slice(0, cutIdx).map((e) => e.message),
+    firstKeptEntryId: liveMessages[cutIdx].entry.id,
+    compactAll: false,
+  };
+}
+
+const REASON_MESSAGES: Record<OwnCutCancelReason, string> = {
+  no_live_messages: "pi-vcc: Nothing to compact (no live messages)",
+  too_few_live_messages: "pi-vcc: Too few messages to compact",
+};
+
+export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
+  pi.on("session_before_compact", (event, ctx) => {
+    const { preparation, branchEntries, customInstructions } = event;
+    const settings = loadSettings();
+
+    // Per-model threshold check — applies regardless of which compactor handles
+    // the actual summary. When pi-core's global threshold triggers compaction
+    // but the current model's per-model threshold hasn't been crossed yet,
+    // cancel to avoid compacting prematurely.
+    //
+    // This is NOT applied to explicit /pi-vcc commands — if the user asked
+    // for a compaction, honor it.
+    const isPiVcc = customInstructions === PI_VCC_COMPACT_INSTRUCTION;
+    if (!isPiVcc && !isProactiveTriggerActive()) {
+      const threshold = getModelThreshold(settings, ctx.model);
+      if (threshold) {
+        const contextWindow = ctx.model?.contextWindow ?? 0;
+        const reserve = resolveReserveTokens(threshold, contextWindow);
+        if (reserve != null && contextWindow > 0) {
+          const effectiveThreshold = contextWindow - reserve;
+          if (preparation.tokensBefore <= effectiveThreshold) {
+            try {
+              const pct = Math.round((preparation.tokensBefore / contextWindow) * 100);
+              ctx?.ui?.notify?.(
+                `pi-vcc: Skipped compaction — ${pct}% of context window used (threshold: ${formatTokens(effectiveThreshold)} tok)`,
+                "info",
+              );
+            } catch {}
+            return { cancel: true };
+          }
+        }
+      }
+    }
+
+    // Always handle explicit /pi-vcc marker.
+    // Otherwise, only handle when user opted in via settings.
+    if (!isPiVcc && !settings.overrideDefaultCompaction) return;
+
+    const ownCut = buildOwnCut(branchEntries as any[]);
+    if (!ownCut.ok) {
+      const lastComp = [...branchEntries].reverse().find((e: any) => e.type === "compaction");
+      const lastCompIdx = lastComp ? (branchEntries as any[]).indexOf(lastComp) : -1;
+
+      // Recompute liveMessages view (same logic as buildOwnCut) for diagnostic
+      const lastKeptId: string | undefined = (lastComp as any)?.firstKeptEntryId;
+      const hasPriorCompaction = lastCompIdx >= 0;
+      const hasValidKeptId = !!lastKeptId && (branchEntries as any[]).some((e: any) => e.id === lastKeptId);
+      const diagOrphan = hasPriorCompaction && !hasValidKeptId;
+      const liveRoles: string[] = [];
+      if (diagOrphan) {
+        for (let i = lastCompIdx + 1; i < branchEntries.length; i++) {
+          const e = (branchEntries as any[])[i];
+          if (e.type === "compaction") continue;
+          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+        }
+      } else {
+        let foundKept = !lastKeptId;
+        for (const e of branchEntries as any[]) {
+          if (!foundKept && e.id === lastKeptId) foundKept = true;
+          if (!foundKept) continue;
+          if (e.type === "compaction") continue;
+          if (e.type === "message" && e.message) liveRoles.push(e.message.role);
+        }
+      }
+      const userIndices = liveRoles.reduce<number[]>((acc, r, i) => (r === "user" ? (acc.push(i), acc) : acc), []);
+
+      dbg(settings, {
+        cancelled: true,
+        reason: ownCut.reason,
+        isPiVcc,
+        counts: {
+          total: branchEntries.length,
+          messages: (branchEntries as any[]).filter((e: any) => e.type === "message").length,
+          compactions: (branchEntries as any[]).filter((e: any) => e.type === "compaction").length,
+          entriesAfterLastCompaction: lastCompIdx >= 0 ? branchEntries.length - lastCompIdx - 1 : null,
+        },
+        liveMessages: {
+          count: liveRoles.length,
+          userCount: userIndices.length,
+          firstUserIdx: userIndices[0] ?? null,
+          lastUserIdx: userIndices[userIndices.length - 1] ?? null,
+          roleSequence: liveRoles.length <= 30
+            ? liveRoles
+            : [...liveRoles.slice(0, 10), "...", ...liveRoles.slice(-10)],
+        },
+        lastCompaction: lastComp ? {
+          hasFirstKeptEntryId: !!(lastComp as any).firstKeptEntryId,
+          foundInBranch: (lastComp as any).firstKeptEntryId
+            ? (branchEntries as any[]).some((e: any) => e.id === (lastComp as any).firstKeptEntryId)
+            : null,
+        } : null,
+        tail: (branchEntries as any[]).slice(-5).map((e: any) => ({
+          type: e.type,
+          role: e.type === "message" ? e.message?.role : undefined,
+          hasContent: e.type === "message" ? e.message?.content != null : undefined,
+        })),
+      });
+
+      try {
+        ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
+      } catch {}
+      return { cancel: true };
+    }
+
+    const agentMessages = ownCut.messages;
+    const firstKeptEntryId = ownCut.firstKeptEntryId;
+    const messages = agentMessages;
+
+    // Count kept messages and estimate tokens
+    const keptIdx = (branchEntries as any[]).findIndex((e: any) => e.id === firstKeptEntryId);
+    const keptEntries = keptIdx >= 0
+      ? (branchEntries as any[]).slice(keptIdx).filter((e: any) => e.type === "message")
+      : [];
+    const keptChars = keptEntries.reduce((sum: number, e: any) => {
+      const c = e.message?.content;
+      if (typeof c === "string") return sum + c.length;
+      if (Array.isArray(c)) return sum + c.reduce((s: number, p: any) => {
+        if (p.text) return s + p.text.length;
+        if (p.type === "toolCall") return s + (p.name?.length ?? 0) + (typeof p.input === "string" ? p.input.length : JSON.stringify(p.input ?? "").length);
+        if (p.type === "toolResult") return s + (typeof p.content === "string" ? p.content.length : JSON.stringify(p.content ?? "").length);
+        return s;
+      }, 0);
+      return sum;
+    }, 0);
+    lastStats = {
+      summarized: agentMessages.length,
+      kept: keptEntries.length,
+      keptTokensEst: Math.round(keptChars / 4),
+    };
+
+    const config = settings;
+
+    // Compute entry-ID range for compaction-scoped recall
+    const messageRange = computeMessageRange(
+      branchEntries as any[],
+      firstKeptEntryId,
+    );
+
+    const compileInput: CompileInput = {
+      messages,
+      previousSummary: preparation.previousSummary,
+      fileOps: {
+        readFiles: [...preparation.fileOps.read],
+        modifiedFiles: [...preparation.fileOps.written, ...preparation.fileOps.edited],
+      },
+    };
+
+    const summary = compile(compileInput);
+
+    const branchIds = branchEntries.map((e: any) => e.id);
+    const cutIdx = branchIds.indexOf(firstKeptEntryId);
+    const cutWindow = cutIdx >= 0
+      ? branchEntries.slice(Math.max(0, cutIdx - 3), Math.min(branchEntries.length, cutIdx + 3)).map((e: any) => ({
+          id: e.id,
+          type: e.type,
+          role: e.type === "message" ? e.message?.role : undefined,
+          preview: e.type === "message" ? previewContent(e.message?.content) : undefined,
+        }))
+      : [];
+
+    dbg(config, {
+      usedOwnCut: true,
+      messagesToSummarize: agentMessages.length,
+      messagesPreviewHead: agentMessages.slice(0, 3).map((m: any) => ({ role: m.role, preview: previewContent(m.content) })),
+      messagesPreviewTail: agentMessages.slice(-3).map((m: any) => ({ role: m.role, preview: previewContent(m.content) })),
+      convertedMessages: messages.length,
+      firstKeptEntryId,
+      messageRange,
+      cutWindow,
+      tokensBefore: preparation.tokensBefore,
+      summaryLength: summary.length,
+      summaryPreview: summary.slice(0, 500),
+      sections: [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]),
+    });
+
+    const sections = [...summary.matchAll(/^\[(.+?)\]/gm)].map((m) => m[1]);
+    const details: PiVccCompactionDetails = {
+      compactor: "pi-vcc",
+      version: 1,
+      sections,
+      sourceMessageCount: agentMessages.length,
+      previousSummaryUsed: Boolean(preparation.previousSummary),
+      messageRange,
+      compressionRatio: preparation.tokensBefore > 0
+        ? Math.round(preparation.tokensBefore / Math.max(1, agentMessages.length))
+        : undefined,
+      timestamp: new Date().toISOString(),
+      tokensBefore: preparation.tokensBefore || undefined,
+      keptCount: lastStats?.kept || undefined,
+      keptTokensEst: lastStats?.keptTokensEst || undefined,
+    };
+
+    lastCompactWasPiVcc = isPiVcc;
+    lastCompactHandledByVcc = true;
+
+    // Signal to neuralwatt-mcr that pi-vcc is handling compaction
+    // so it doesn't cancel the event. Without this flag, neuralwatt-mcr
+    // returns { cancel: true } for MCR models and pi-vcc's summary is
+    // discarded by the runner's short-circuit.
+    (event as any)._piVccOverriding = true;
+
+    return {
+      compaction: {
+        summary,
+        details,
+        tokensBefore: preparation.tokensBefore,
+        firstKeptEntryId,
+      },
+    };
+  });
+
+  // After compaction completes, check if the agent loop stalled and needs
+  // an invisible continue to resume.  This handles threshold compaction
+  // where willRetry=false — pi-core doesn't auto-retry, and the agent loop
+  // exits because hasQueuedMessages() returns false.  If the last message in
+  // the rebuilt context is an assistant mid-task (tool_use, length, or error
+  // that isn't a clean end_turn), the agent was interrupted and should
+  // continue.
+  pi.on("session_compact", (event, ctx) => {
+    // Only act when pi-vcc drove the compaction
+    if (!lastCompactHandledByVcc) return;
+    lastCompactHandledByVcc = false;
+
+    // Fire success toast for /compact path only (delayed to let UI settle).
+    // /pi-vcc path uses its own onComplete callback in the command handler.
+    if (!lastCompactWasPiVcc) {
+      const stats = lastStats;
+      if (stats) {
+        setTimeout(() => {
+          try {
+            ctx?.ui?.notify?.(
+              `pi-vcc: ${stats.summarized} source entries processed; tail kept ${stats.kept} (~${formatTokens(stats.keptTokensEst)} tok).`,
+              "info",
+            );
+          } catch {}
+        }, 500);
+      }
+    }
+
+    // Determine if the agent needs to continue after compaction.
+    // After rebuildSessionContext, the agent's state.messages are updated.
+    // Check the last message: if it's an assistant message that isn't a
+    // clean stop, the agent was mid-task and needs to resume.
+    //
+    // We do NOT continue when:
+    // - Last message is user/toolResult (agent can continue naturally)
+    // - Last message is assistant with stopReason=stop (task finished)
+    // - Last message is assistant with stopReason=aborted (user cancelled)
+    // - Last message is assistant with stopReason=error (pi-retry handles
+    //   retry via its agent_end handler — avoid duplicate triggerInvisibleContinue)
+    //
+    // We DO continue when:
+    // - Last message is assistant with stopReason=toolUse (mid-tool cycle)
+    // - Last message is assistant with stopReason=length (hit max tokens)
+    // - Compact-all (firstKeptEntryId="") — context is just the summary,
+    //   the agent needs to re-enter the loop to continue the task
+    try {
+      const entries = ctx.sessionManager.getEntries();
+      // Walk backwards to find the last message entry
+      let lastMsg: { role: string; stopReason?: string; content?: unknown } | undefined;
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = (entries as any[])[i];
+        if (e.type === "message" && e.message) {
+          lastMsg = e.message;
+          break;
+        }
+      }
+      if (!lastMsg || lastMsg.role !== "assistant") return;
+
+      // Agent completed its turn cleanly — no continuation needed
+      if (lastMsg.stopReason === "stop") return;
+
+      // Agent was aborted by user — don't auto-continue
+      if (lastMsg.stopReason === "aborted") return;
+
+      // Agent hit an error — pi-retry handles this via its agent_end handler.
+      // If we also fire triggerInvisibleContinue, both extensions race
+      // to call prompt([]), causing "Agent is already processing" (wasteful)
+      // or a duplicate continuation. Let pi-retry own error retries.
+      if (lastMsg.stopReason === "error") return;
+
+      // Agent was mid-task (toolUse or length) — needs to continue.
+      triggerInvisibleContinue();
+    } catch {
+      // Non-critical — if context inspection fails, don't block compaction
+    }
+  });
+};

package/src/hooks/proactive-threshold.ts

@@ -0,0 +1,131 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadSettings, getModelThreshold, resolveReserveTokens } from "../core/settings";
+
+const formatTokens = (n: number): string => {
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+};
+
+// Cooldown after compaction to prevent double-trigger.
+// Set immediately when we call ctx.compact() AND on session_compact,
+// cleared after 3 seconds.
+let lastCompactTime = 0;
+const COOLDOWN_MS = 3000;
+
+// Flag: when true, session_before_compact should NOT cancel even if
+// tokensBefore is below the per-model threshold. This is set when
+// our proactive trigger calls ctx.compact() and cleared when
+// session_compact fires. It prevents the threshold guard from
+// cancelling a compaction that we ourselves initiated.
+let proactiveTriggerActive = false;
+
+const setCooldown = () => { lastCompactTime = Date.now(); };
+const isCoolingDown = () => Date.now() - lastCompactTime < COOLDOWN_MS;
+
+/** Check if a proactive trigger is currently in flight. */
+export const isProactiveTriggerActive = () => proactiveTriggerActive;
+
+/** Reset all proactive state (for testing / session start). */
+export const resetProactiveState = () => {
+  lastCompactTime = 0;
+  proactiveTriggerActive = false;
+};
+
+/**
+ * Check if per-model threshold has been crossed and trigger compaction
+ * if so. Safe to call from multiple event handlers — cooldown prevents
+ * double-triggering.
+ */
+const checkAndTrigger = (ctx: { model?: any; getContextUsage?: () => any; compact?: () => void; ui?: any }, source: string) => {
+  const settings = loadSettings();
+  const threshold = getModelThreshold(settings, ctx.model);
+
+  // No threshold → nothing to do (pi-core's global threshold owns it)
+  if (!threshold) return;
+
+  const contextWindow = ctx.model?.contextWindow ?? 0;
+  const reserve = resolveReserveTokens(threshold, contextWindow);
+  if (reserve == null || contextWindow <= 0) return;
+
+  const usage = ctx.getContextUsage?.();
+  if (!usage || usage.tokens === null) return;
+
+  // This threshold's compaction trigger point
+  const effectiveThreshold = contextWindow - reserve;
+
+  // Only trigger if context EXCEEDS the threshold.
+  if (usage.tokens <= effectiveThreshold) return;
+
+  // Cooldown guard — prevent double-trigger within 3s of last compaction.
+  if (isCoolingDown()) return;
+
+  try {
+    const pct = Math.round((usage.tokens / contextWindow) * 100);
+    ctx?.ui?.notify?.(
+      `pi-vcc: [${source}] Context at ${pct}% exceeds threshold (${formatTokens(effectiveThreshold)} tok). Compacting...`,
+      "info",
+    );
+  } catch {}
+
+  // Set cooldown IMMEDIATELY (before ctx.compact() runs) to prevent
+  // pi-core's own _checkCompaction from also triggering compaction
+  // on the same turn.
+  setCooldown();
+
+  // Mark that this compaction was triggered by us, so session_before_compact
+  // doesn't cancel it if tokensBefore differs from getContextUsage().
+  proactiveTriggerActive = true;
+
+  ctx.compact?.();
+};
+
+/**
+ * Registers proactive per-model compaction thresholds.
+ *
+ * Three triggers:
+ *
+ * 1. `agent_end` — after each agent run completes, check if context
+ *    exceeds the current model's per-model threshold. If the per-model
+ *    threshold is *lower* than pi-core's global threshold (meaning the
+ *    model wants to compact *earlier*), pi-core won't trigger compaction
+ *    at this point. We step in and trigger it proactively.
+ *
+ * 2. `model_select` — when switching to a model with a lower effective
+ *    threshold, the current context may already exceed the new model's
+ *    capacity. Trigger compaction immediately.
+ *
+ * 3. `session_compact` — cooldown tracking + clear proactiveTriggerActive.
+ *    After any compaction completes, we set a cooldown to prevent
+ *    double-triggering and clear the self-initiated flag.
+ *
+ * `session_before_compact` reads `isProactiveTriggerActive()` to decide
+ * whether to cancel. When our proactive trigger fires, ctx.compact() is
+ * queued but hasn't run yet. By the time session_before_compact actually
+ * fires, tokensBefore may differ from the getContextUsage() snapshot
+ * that triggered the compact. Without the flag, the threshold guard would
+ * cancel the compaction we ourselves requested — producing confusing
+ * "Compacting..." then "Skipped compaction" notifications.
+ */
+export const registerProactiveThresholdHook = (pi: ExtensionAPI) => {
+  // Proactive compaction after each agent run
+  pi.on("agent_end", (_event, ctx) => {
+    checkAndTrigger(ctx, "auto");
+  });
+
+  // Proactive compaction on model switch
+  pi.on("model_select", (_event, ctx) => {
+    checkAndTrigger(ctx, "model-switch");
+  });
+
+  // Track compaction completion: set cooldown and clear self-initiated flag
+  pi.on("session_compact", () => {
+    setCooldown();
+    proactiveTriggerActive = false;
+  });
+
+  // Reset state on session start so state doesn't leak between sessions
+  pi.on("session_start", () => {
+    lastCompactTime = 0;
+    proactiveTriggerActive = false;
+  });
+};