@monotykamary/pi-vcc 0.6.3 → 0.7.0

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.3",
+  "version": "0.7.0",
   "description": "Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls",
   "main": "index.ts",
   "keywords": [

package/src/core/settings.ts

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
 import { dirname, join } from "path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-const SETTINGS_PATH_DEFAULT = join(homedir(), ".pi", "agent", "pi-vcc-config.json");
-const settingsPath = (): string => process.env.PI_VCC_CONFIG_PATH ?? SETTINGS_PATH_DEFAULT;
+const settingsPath = (): string =>
+  process.env.PI_VCC_CONFIG_PATH ?? join(getAgentDir(), "pi-vcc-config.json");
 /** Backwards-compat export. Resolves at access time, not import time. */
 const SETTINGS_PATH = settingsPath();
 
@@ -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"));
@@ -156,7 +193,7 @@ export function loadSettings(): PiVccSettings {
 }
 
 /**
- * Ensure ~/.pi/agent/pi-vcc-config.json exists with default keys.
+ * Ensure the pi-vcc config file (default ~/.pi/agent/pi-vcc-config.json) exists with default keys.
  * - File missing → create with full default block.
  * - File exists but invalid JSON → no-op (don't clobber user file).
  * - File exists and valid → fill in missing default keys, preserve existing values.

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