@monotykamary/pi-vcc 0.6.4 → 0.7.1

package/README.md

@@ -211,7 +211,7 @@ pi-vcc is one of four compaction approaches in the AI coding-agent ecosystem. He
 - **Error resolution detection** — tsc errors in `[Outstanding Context]` are tagged `[RESOLVED]` when the file they reference was subsequently edited, letting the model skip stale errors.
 - **Task-boundary-aware cut** — compaction splits at complete conversational turns, not mid-tool-call. If the assistant's response is in-flight (unmatched tool calls), the cut pushes back to keep the whole turn in the tail.
 - **Structured anchors** — `[Anchors]` section lists commit hashes, error IDs, and key file paths for zero-tool-call recall. The model can find references at a glance instead of calling `vcc_recall`.
-- **Per-model and global compaction thresholds** — configure different `reserveTokens` or `compactPercent` per model and globally, so models with different context windows compact at the right time. Proactive triggering on `agent_end` and `model_select` events compacts earlier for small-context models. Applies to both pi-vcc and pi-core compaction.
+- **Per-model and global compaction thresholds** — configure different `reserveTokens`, `compactAtTokens`, or `compactPercent` per model and globally, so models with different context windows compact at the right time. Proactive triggering on `agent_end` and `model_select` events compacts earlier for small-context models. Applies to both pi-vcc and pi-core compaction.
 
 ## Install
 
@@ -567,24 +567,25 @@ Config lives at `~/.pi/agent/pi-vcc-config.json` (auto-scaffolded on first load
   "modelThresholds": {
     "neuralwatt/zai-org/GLM-5.1-FP8": { "reserveTokens": 32768 },
     "neuralwatt/moonshotai/Kimi-K2.6": { "compactPercent": 65 },
-    "neuralwatt/neuralwatt/glm-5.1-long": { "compactPercent": 80 }
+    "neuralwatt/glm-5.1-long": { "compactAtTokens": 150000 }
   },
-  "globalThreshold": { "compactPercent": 70 }
+  "globalThreshold": { "compactAtTokens": 150000 }
 }
 ```
 
 - **`overrideDefaultCompaction`** *(default `true`)*: when `true` (default), pi-vcc handles all compaction paths (`/compact`, auto-threshold, `/pi-vcc`). Set `false` to let pi core handle `/compact` and auto-threshold compactions via its default LLM-based compaction.
 - **`debug`** *(default `false`)*: when `true`, each compaction writes detailed info to `/tmp/pi-vcc-debug.json` — message counts, cut boundary, summary preview, sections.
 - **`modelThresholds`** *(default: none)*: per-model compaction thresholds. Keys match against `"provider/modelId"` (e.g., `"neuralwatt/zai-org/GLM-5.1-FP8"`) or just `"modelId"` (e.g., `"GLM-5.1"` — matched only when `provider/modelId` doesn't). Each value has:
-  - **`reserveTokens`**: tokens to reserve for the LLM response. Overrides pi-core's global `compaction.reserveTokens` for matching models. Controls *when* compaction triggers: `contextTokens > contextWindow − reserveTokens`. A higher value compacts earlier (more conservative); a lower value lets context grow larger. Takes precedence over `compactPercent` when both are set.
-  - **`compactPercent`**: compaction trigger as a percentage of context window (1–99). Compaction fires when `contextTokens > contextWindow × compactPercent / 100`. E.g. `65` means "compact when context is 65% full". Ignored when `reserveTokens` is also set.
+  - **`reserveTokens`**: tokens to reserve for the LLM response. Overrides pi-core's global `compaction.reserveTokens` for matching models. Controls *when* compaction triggers: `contextTokens > contextWindow − reserveTokens`. A higher value compacts earlier (more conservative); a lower value lets context grow larger. Takes precedence over `compactAtTokens` and `compactPercent` when multiple are set.
+  - **`compactAtTokens`**: absolute context token count where compaction triggers: `contextTokens > compactAtTokens`. Useful when you want the same trigger point across models with different context windows, such as `{ "compactAtTokens": 150000 }`. Takes precedence over `compactPercent` when both are set.
+  - **`compactPercent`**: compaction trigger as a percentage of context window (1–99). Compaction fires when `contextTokens > contextWindow × compactPercent / 100`. E.g. `65` means "compact when context is 65% full". Ignored when `reserveTokens` or `compactAtTokens` is also set.
   - **`keepRecentTokens`** *(optional)*: advisory token budget for pi-core's default compaction. Pi-vcc's own `buildOwnCut` uses task-boundary heuristics, so this only affects pi-core's cut when `overrideDefaultCompaction` is `false`.
-- **`globalThreshold`** *(default: none)*: global threshold applied to all models not matched by `modelThresholds`. Uses `compactPercent` or `reserveTokens` (`compactPercent` is easier — e.g. `65` means "compact at 65% full"). If omitted, pi-core's global `compaction.reserveTokens` applies (no override).
+- **`globalThreshold`** *(default: none)*: global threshold applied to all models not matched by `modelThresholds`. Uses `reserveTokens`, `compactAtTokens`, or `compactPercent`. If omitted, pi-core's global `compaction.reserveTokens` applies (no override).
 - **`defaultThreshold`** *(default: none, deprecated)*: use `globalThreshold` instead. Backward compatible — still works.
 
 ### How compaction thresholds work
 
-Pi-core's auto-compaction triggers when `contextTokens > contextWindow − reserveTokens`. The global `reserveTokens` (default 16384) is one-size-fits-all — but different models have very different context windows and cost profiles.
+Pi-core's auto-compaction triggers when `contextTokens > contextWindow − reserveTokens`. The global `reserveTokens` (default 16384) is one-size-fits-all — but different models have very different context windows and cost profiles. Pi-vcc also supports `compactAtTokens` when you want an absolute trigger point independent of a model's context window.
 
 Pi-vcc's thresholds provide proactive compaction at both the per-model and global level:
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@monotykamary/pi-vcc",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@monotykamary/pi-vcc",
-      "version": "0.6.3",
+      "version": "0.7.0",
       "devDependencies": {
         "knip": "6.14.1",
         "typescript": "6.0.3"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-vcc",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "description": "Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls",
   "main": "index.ts",
   "keywords": [

package/src/core/settings.ts

@@ -19,9 +19,20 @@ export interface ModelThreshold {
    * A higher value compacts earlier (more conservative); a lower value
    * lets context grow larger before compacting.
    *
-   * Takes precedence over compactPercent when both are set.
+   * Takes precedence over compactAtTokens and compactPercent when multiple are set.
    */
   reserveTokens?: number;
+  /**
+   * Absolute context token count where compaction triggers.
+   *
+   * This controls *when* compaction triggers:
+   *   contextTokens > compactAtTokens
+   *
+   * Useful when you want the same trigger point across models with
+   * different context windows. Ignored when reserveTokens is also set;
+   * takes precedence over compactPercent.
+   */
+  compactAtTokens?: number;
   /**
    * Compaction trigger as a percentage of context window (1–99).
    * Compaction fires when: contextTokens > contextWindow × compactPercent / 100
@@ -29,7 +40,7 @@ export interface ModelThreshold {
    * E.g. compactPercent: 65 means "compact when context is 65% full",
    * equivalent to reserveTokens = 35% of contextWindow.
    *
-   * Ignored when reserveTokens is also set.
+   * Ignored when reserveTokens or compactAtTokens is also set.
    */
   compactPercent?: number;
   /**
@@ -61,17 +72,16 @@ export interface PiVccSettings {
    * "provider/modelId" (e.g., "neuralwatt/zai-org/GLM-5.1-FP8") or
    * just "modelId" (e.g., "GLM-5.1-FP8").
    *
-   * When a model matches, its reserveTokens/compactPercent overrides
-   * pi-core's global compaction.reserveTokens for the *when to compact*
-   * decision. This lets different models compact at different context
-   * fill levels.
+   * When a model matches, its reserveTokens/compactAtTokens/compactPercent
+   * overrides pi-core's global compaction.reserveTokens for the *when to
+   * compact* decision. This lets different models compact at different
+   * context fill levels or absolute token counts.
    */
   modelThresholds?: Record<string, ModelThreshold>;
   /**
    * Global threshold applied to all models not matched by modelThresholds.
-   * Uses compactPercent or reserveTokens (compactPercent is easier — e.g.
-   * 65 means "compact at 65% full"). If omitted, pi-core's global
-   * compaction settings apply (no override).
+   * Uses reserveTokens, compactAtTokens, or compactPercent. If omitted,
+   * pi-core's global compaction settings apply (no override).
    */
   globalThreshold?: ModelThreshold;
   /**
@@ -91,8 +101,8 @@ const DEFAULT_SETTINGS: PiVccSettings = {
  * Lookup order:
  *  1. Exact match on "provider/modelId" key
  *  2. Exact match on "modelId" key
- *  4. globalThreshold from settings
- *  5. undefined (no override — pi-core's global settings apply)
+ *  3. globalThreshold from settings
+ *  4. undefined (no override — pi-core's global settings apply)
  */
 export function getModelThreshold(
   settings: PiVccSettings,
@@ -136,6 +146,33 @@ export function resolveReserveTokens(
   return undefined;
 }
 
+/**
+ * Resolve the context token count where compaction should trigger.
+ *
+ * Precedence: reserveTokens > compactAtTokens > compactPercent.
+ * Returns undefined when the threshold cannot produce a usable trigger.
+ */
+export function resolveTriggerTokens(
+  threshold: ModelThreshold,
+  contextWindow: number,
+): number | undefined {
+  if (contextWindow <= 0) return undefined;
+
+  if (threshold.reserveTokens != null) {
+    return contextWindow - threshold.reserveTokens;
+  }
+
+  if (threshold.compactAtTokens != null) {
+    const tokens = threshold.compactAtTokens;
+    if (!Number.isFinite(tokens) || tokens < 1) return undefined;
+    return Math.round(tokens);
+  }
+
+  const reserve = resolveReserveTokens(threshold, contextWindow);
+  if (reserve == null) return undefined;
+  return contextWindow - reserve;
+}
+
 const readJson = (path: string): Record<string, unknown> | null => {
   try {
     return JSON.parse(readFileSync(path, "utf-8"));

package/src/hooks/before-compact.ts

@@ -150,7 +150,88 @@ const findMidCycleBoundary = (liveMessages: EntryWithMessage[]): number => {
   return best;
 };
 
-export function buildOwnCut(branchEntries: any[]): OwnCutResult {
+/** Rough token estimate (chars/4) for a live message, consistent with the
+ * kept-tokens estimate used elsewhere in this module. */
+function estimateMessageTokens(message: { content: unknown }): number {
+  const c = message.content;
+  let chars = 0;
+  if (typeof c === "string") {
+    chars = c.length;
+  } else if (Array.isArray(c)) {
+    for (const part of c as any[]) {
+      if (part.text) chars += part.text.length;
+      else if (part.type === "toolCall") {
+        const args = part.arguments ?? part.input;
+        chars += (part.name?.length ?? 0) + (typeof args === "string" ? args.length : JSON.stringify(args ?? "").length);
+      } else if (part.type === "toolResult") {
+        chars += typeof part.content === "string" ? part.content.length : JSON.stringify(part.content ?? "").length;
+      } else if (part.type === "thinking") {
+        chars += (part.thinking?.length ?? 0);
+      }
+    }
+  }
+  return Math.ceil(chars / 4);
+}
+
+/** Find a completed tool-cycle boundary within `suffix` such that the kept
+ * tail (suffix[boundary+1 .. end]) fits within `budgetTokens`, keeping as
+ * much recent context as possible. Returns the index of the first message to
+ * KEEP, or -1 when the suffix can't be split to fit (single oversized cycle,
+ * or no completed cycles). */
+const findSuffixSplitPoint = (
+  suffix: EntryWithMessage[],
+  budgetTokens: number,
+): number => {
+  if (suffix.length <= 2) return -1;
+
+  // Completed-cycle end-indices (toolResult closing a cycle). Same detection
+  // as findMidCycleBoundary.
+  const cycleEnds: number[] = [];
+  let currentAssistantIdx = -1;
+  const pendingCalls = new Set<string>();
+  for (let i = 0; i < suffix.length; i++) {
+    const msg = suffix[i].message;
+    if (msg.role === "user") { currentAssistantIdx = -1; pendingCalls.clear(); 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) {
+        cycleEnds.push(i);
+        currentAssistantIdx = -1;
+      }
+    }
+  }
+  if (cycleEnds.length === 0) return -1;
+
+  // tailTokens[i] = tokens of suffix[i .. end].
+  const tailTokens: number[] = new Array(suffix.length + 1).fill(0);
+  for (let i = suffix.length - 1; i >= 0; i--) {
+    tailTokens[i] = tailTokens[i + 1] + estimateMessageTokens(suffix[i].message);
+  }
+  // Earliest cycle boundary whose kept tail fits — keeps the most recent
+  // context while staying under budget. boundary+1 must be < length so the
+  // kept tail is non-empty.
+  for (const boundary of cycleEnds) {
+    if (boundary + 1 < suffix.length && tailTokens[boundary + 1] <= budgetTokens) {
+      return boundary + 1;
+    }
+  }
+  return -1;
+};
+
+export function buildOwnCut(branchEntries: any[], options?: { maxKeptTokens?: number }): OwnCutResult {
+  const maxKeptTokens = options?.maxKeptTokens ?? 0;
   // Find the last compaction entry and its firstKeptEntryId
   let lastCompactionIdx = -1;
   let lastKeptId: string | undefined;
@@ -235,6 +316,38 @@ export function buildOwnCut(branchEntries: any[]): OwnCutResult {
     }
   }
 
+  // Oversized-turn guard (opt-in via options.maxKeptTokens > 0). When the
+  // kept suffix — the most recent turn from the last user message — exceeds
+  // the budget, keeping it whole would re-overflow on the compaction retry.
+  // Split the turn at a completed tool-cycle boundary so the oversized early
+  // part (typically a giant tool result) is summarized and only recent cycles
+  // that fit are kept. If a single cycle is itself oversized (or there are no
+  // completed cycles to split at), fall back to compact-all — safe because
+  // pi-vcc compiles summaries statically (no LLM call that could overflow).
+  if (cutIdx > 0 && maxKeptTokens > 0) {
+    const suffix = liveMessages.slice(cutIdx);
+    let suffixTokens = 0;
+    for (const e of suffix) suffixTokens += estimateMessageTokens(e.message);
+    if (suffixTokens > maxKeptTokens) {
+      const splitIdx = findSuffixSplitPoint(suffix, maxKeptTokens);
+      if (splitIdx >= 0) {
+        const globalIdx = cutIdx + splitIdx;
+        return {
+          ok: true,
+          messages: liveMessages.slice(0, globalIdx).map((e) => e.message),
+          firstKeptEntryId: liveMessages[globalIdx].entry.id,
+          compactAll: false,
+        };
+      }
+      return {
+        ok: true,
+        messages: liveMessages.map((e) => e.message),
+        firstKeptEntryId: "",
+        compactAll: true,
+      };
+    }
+  }
+
   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
@@ -301,7 +414,20 @@ export const registerBeforeCompactHook = (pi: ExtensionAPI) => {
     // Otherwise, only handle when user opted in via settings.
     if (!isPiVcc && !settings.overrideDefaultCompaction) return;
 
-    const ownCut = buildOwnCut(branchEntries as any[]);
+    // Budget the kept tail so that summary + kept + system/tools + the model's
+    // OUTPUT budget (maxTokens) all fit in the window. Without reserving
+    // maxTokens, the compaction-retry request can be rejected upfront
+    // (input + maxTokens > contextWindow) and re-overflow. Falls back to
+    // pi-core's keepRecentTokens when the window is unknown.
+    const contextWindow = (ctx as any)?.model?.contextWindow ?? 0;
+    const maxTokens = (ctx as any)?.model?.maxTokens ?? 0;
+    const keepRecentTokens = (preparation as any)?.settings?.keepRecentTokens ?? 20000;
+    const overhead = contextWindow > 0 ? Math.min(32768, Math.floor(contextWindow * 0.2)) : 32768;
+    const outputReserve = maxTokens > 0 ? maxTokens : Math.floor(contextWindow * 0.5);
+    const maxKeptTokens = contextWindow > 0
+      ? Math.max(2048, contextWindow - outputReserve - overhead)
+      : keepRecentTokens;
+    const ownCut = buildOwnCut(branchEntries as any[], { maxKeptTokens });
     if (!ownCut.ok) {
       const lastComp = [...branchEntries].reverse().find((e: any) => e.type === "compaction");
       const lastCompIdx = lastComp ? (branchEntries as any[]).indexOf(lastComp) : -1;

package/src/hooks/proactive-threshold.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadSettings, getModelThreshold, resolveReserveTokens } from "../core/settings";
+import { loadSettings, getModelThreshold, resolveTriggerTokens } from "../core/settings";
 
 const formatTokens = (n: number): string => {
   if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
@@ -32,7 +32,7 @@ export const resetProactiveState = () => {
 };
 
 /**
- * Check if per-model threshold has been crossed and trigger compaction
+ * Check if a configured threshold has been crossed and trigger compaction
  * if so. Safe to call from multiple event handlers — cooldown prevents
  * double-triggering.
  */
@@ -44,14 +44,13 @@ const checkAndTrigger = (ctx: { model?: any; getContextUsage?: () => any; compac
   if (!threshold) return;
 
   const contextWindow = ctx.model?.contextWindow ?? 0;
-  const reserve = resolveReserveTokens(threshold, contextWindow);
-  if (reserve == null || contextWindow <= 0) return;
+  const effectiveThreshold = resolveTriggerTokens(threshold, contextWindow);
+  if (effectiveThreshold == null) return;
 
   const usage = ctx.getContextUsage?.();
   if (!usage || usage.tokens === null) return;
 
-  // This threshold's compaction trigger point
-  const effectiveThreshold = contextWindow - reserve;
+  // This threshold's compaction trigger point.
 
   // Only trigger if context EXCEEDS the threshold.
   if (usage.tokens <= effectiveThreshold) return;
@@ -80,19 +79,18 @@ const checkAndTrigger = (ctx: { model?: any; getContextUsage?: () => any; compac
 };
 
 /**
- * Registers proactive per-model compaction thresholds.
+ * Registers proactive configured 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.
+ *    exceeds the active configured threshold. If that threshold is lower
+ *    than pi-core's global threshold (meaning this config wants to compact
+ *    earlier), pi-core won't trigger compaction — so we do.
  *
- * 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.
+ * 2. `model_select` — when switching models, the new model may have a
+ *    different threshold. Check immediately in case current context exceeds
+ *    the new threshold.
  *
  * 3. `session_compact` — cooldown tracking + clear proactiveTriggerActive.
  *    After any compaction completes, we set a cooldown to prevent