pi-condense 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.8.0] - 2026-08-13
+
+- **Both token-budget flush triggers now cap the context window they reason about at 300,000 tokens** (`MAX_BUDGET_WINDOW`, `src/budget.ts`) ([#7](https://github.com/jjuraszek/pi-condense/issues/7)). Previously both scaled purely off the model's advertised window, which made them unreachable as windows grew: on a 1M-window model `autoBudgetThreshold: 0.9` meant 900k tokens - a session ends long before that, so pruning never fired - while the same setting worked on a 200k model. `budgetTurnDelta: 0.1` was worse than late: it meant +100k context growth inside a single turn, which effectively never happens, so the re-arm trigger was dead.
+  - `autoBudgetThreshold` now fires at `min(300_000, threshold * contextWindow)` tokens - your percentage of the model's window, or 300k tokens, whichever comes first. The threshold keeps its literal meaning; the cap is only a ceiling.
+  - `budgetTurnDelta` applies the same ceiling in the other shape - a 300k ceiling on a single turn's *growth* could never bind - so the fraction is measured against `min(contextWindow, 300_000)`: `0.1` means +30k tokens in one turn on any model at or above 300k (+20k on a 200k model, unchanged).
+  - **No new setting, and no behavior change for any model advertising 300k or less, at any setting** - a 256k window at `0.9` still fires at 230.4k. Above 300k flushes happen earlier; nothing ever flushes later than before. Downward control is unaffected: `0.1` on a 1M model still means 100k tokens.
+  - `usageFraction` may now exceed `1.0` above the ceiling (600k tokens on a 1M window returns `2.0`) and is deliberately **not** clamped - clamping would saturate the delta trigger and stop it re-arming.
+  - Docs updated in step: `README.md`, `doc/configuration.md`, `PRUNING.md`. Spec: `doc/specs/2026-08-13-budget-window-cap.md`.
+
 ## [2.7.0] - 2026-08-12
 
 - **Single-chain observability + reload trigger repair ([#6](https://github.com/jjuraszek/pi-condense/issues/6)).** A 5-hour, 256-turn session running one uninterrupted tool chain (no text-only assistant reply ever closed it) accumulated ~195k tokens of raw toolResults while `/pruner status` showed near-zero activity: chain compression (Phase 3) requires *closed* chains by design, and a session reload cleared the in-memory pending queue, leaving the automatic flush trigger stranded even though the branch rescan could recover the work.

package/PRUNING.md

@@ -816,15 +816,17 @@ ACON demonstrates that **compression not only saves tokens but can improve agent
 
 ### Token-budget auto-flush trigger
 
-`autoBudgetThreshold` (default `null`) is an ADDITIONAL flush trigger orthogonal to `pruneOn`. When set to a fraction in `(0, 1]`, the extension evaluates `tokens / contextWindow` at the end of every tool-using turn; when the ratio meets the threshold, all pending batches are flushed immediately regardless of the configured `pruneOn` mode.
+`autoBudgetThreshold` (default `null`) is an ADDITIONAL flush trigger orthogonal to `pruneOn`. When set to a fraction in `(0, 1]`, the extension evaluates context usage at the end of every tool-using turn; when `tokens` reaches `min(MAX_BUDGET_WINDOW, threshold * contextWindow)` - i.e. the configured share of the model's window, or 300,000 tokens, whichever comes first - all pending batches are flushed immediately regardless of the configured `pruneOn` mode.
 
-Why we compute the ratio ourselves rather than using `ContextUsage.percent`: the provider's `percent` field is a 0–100 value, and both it and `tokens` are `null` immediately after a provider-side compaction. Using `tokens / contextWindow` directly gives a 0–1 fraction that matches the config unit and is independently null-safe — a `null` tokens value makes the trigger a no-op until usage is reported again.
+**Why we compute this ourselves rather than using `ContextUsage.percent`:** the provider's `percent` field is a 0-100 value, and both it and `tokens` are `null` immediately after a provider-side compaction. Comparing `tokens` against a token level we derive ourselves keeps the unit unambiguous and is independently null-safe - a `null` tokens value makes the trigger a no-op until usage is reported again. Note this trigger never divides: the fraction form (`tokens / min(contextWindow, MAX_BUDGET_WINDOW)`) belongs to `usageFraction` and the delta trigger below, and reading the threshold as a share of a capped window would be wrong - on a 1M-window model, `0.4` fires at 300,000 tokens, not at 120,000.
+
+**Why the 300k ceiling (`MAX_BUDGET_WINDOW`, `src/budget.ts`):** the trigger was originally a pure fraction of the advertised window, which made it unreachable as windows grew. On a 1M-window model, `0.9` means 900k tokens - a session ends long before that, so users observed "pruning never happens" (issue #7), while the same setting worked on a 200k model. The ceiling is deliberately chosen so it never binds at or below a 300k advertised window (a 256k model at `0.9` still fires at 230.4k), so it changes behavior only where the fraction was already unusable. Users keep full downward control: `0.1` on a 1M model still means 100k tokens.
 
 Lineage: simplified take on DCP's `maxContextLimit` nudging — a single threshold that forces a flush rather than separate nudge/force thresholds.
 
 ### Budget-delta flush
 
-`budgetTurnDelta: number | null` (default `null`) is a per-turn usage-jump trigger ORed with `autoBudgetThreshold`. When set to a fraction in `(0, 1]`, the extension compares the current turn's usage fraction (`tokens / contextWindow`) to the previous turn's and forces a flush if the jump meets or exceeds the delta.
+`budgetTurnDelta: number | null` (default `null`) is a per-turn usage-jump trigger ORed with `autoBudgetThreshold`. When set to a fraction in `(0, 1]`, the extension compares the current turn's usage fraction (`tokens / min(contextWindow, MAX_BUDGET_WINDOW)`) to the previous turn's and forces a flush if the jump meets or exceeds the delta. Because the denominator carries the same 300k ceiling, the required growth is `delta * min(contextWindow, MAX_BUDGET_WINDOW)` tokens: `0.1` = +30k on any model at or above 300k, +20k on a 200k model. The ceiling enters through the denominator here rather than bounding a level, because a 300k ceiling on one turn's growth could never bind. Note the fraction is therefore not bounded by 1 above the ceiling (600k tokens on a 1M window = 2.0) and is deliberately not clamped - clamping would saturate this trigger and stop it re-arming.
 
 Use case: a single enormous tool result can jump context usage by 20–30 percentage points in one turn; `autoBudgetThreshold` misses this until the next turn. `budgetTurnDelta` catches the spike immediately.
 
@@ -971,7 +973,7 @@ Phase 3 (chain compression) only ever acts on **closed** chains - a chain closes
 
 Phase 1 (per-batch summarization) is unaffected by chain closure and remains the only lever for this shape of session. For long autonomous runs where no chain is expected to close:
 
-- Lower `autoBudgetThreshold` (e.g. `0.5`-`0.6` instead of the default `0.8`) so the budget trigger fires well before the open segment dominates the window.
+- Lower `autoBudgetThreshold` (e.g. `0.5`-`0.6` instead of `0.8`) so the budget trigger fires well before the open segment dominates the window. On a window larger than 300k the ceiling already caps the trigger point at 300,000 tokens once `threshold * contextWindow` exceeds it - that is any setting at or above `300k / contextWindow` (`0.3` on a 1M window, `0.75` on a 400k one) - so lowering the setting only matters below that point.
 - Set `budgetTurnDelta` so a single turn's sudden context jump force-flushes even between budget-threshold crossings - this catches spikes a static threshold misses until the next turn.
 
 Neither knob makes a chain close; they just keep Phase 1 flushing on schedule so raw toolResults do not pile up unsummarized for the whole run.

package/README.md

@@ -160,7 +160,7 @@ Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_A
 | `enabled` | `false` | Master switch (or just use `/pruner on`) |
 | `summarizerModel` | `"default"` | Pin a cheap model instead of reusing your active one - see the plan-by-plan table in [doc/configuration.md](doc/configuration.md#choosing-a-summarizer-model) |
 | `pruneOn` | `agent-message` | Trigger mode - see Architecture above |
-| `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn` |
+| `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn`; the trigger point is capped at 300k tokens |
 | `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md"]` | Tool names / path globs that are never pruned |
 | `spillThreshold` | `65536` | Chars above which a single oversized result spills straight to a sidecar file |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/budget.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "bun:test";
-import { shouldBudgetFlush, shouldDeltaFlush, usageFraction } from "./budget.js";
+import { shouldBudgetFlush, shouldDeltaFlush, usageFraction, MAX_BUDGET_WINDOW } from "./budget.js";
 
 const usage = (tokens: number | null, contextWindow: number) =>
   ({ tokens, contextWindow, percent: null }) as any;
@@ -31,6 +31,29 @@ describe("shouldBudgetFlush", () => {
     expect(shouldBudgetFlush(usage(1000, 1000), 1)).toBe(true);
     expect(shouldBudgetFlush(usage(999, 1000), 1)).toBe(false);
   });
+
+  it("exposes the window ceiling as 300k", () => {
+    expect(MAX_BUDGET_WINDOW).toBe(300_000);
+  });
+
+  it("caps the trigger level at MAX_BUDGET_WINDOW on a huge window", () => {
+    expect(shouldBudgetFlush(usage(300_000, 1_000_000), 0.4)).toBe(true);
+    expect(shouldBudgetFlush(usage(299_999, 1_000_000), 0.4)).toBe(false);
+    expect(shouldBudgetFlush(usage(300_000, 1_000_000), 0.9)).toBe(true);
+  });
+
+  it("leaves models at or below the ceiling unchanged", () => {
+    expect(shouldBudgetFlush(usage(80_000, 200_000), 0.4)).toBe(true);
+    expect(shouldBudgetFlush(usage(79_999, 200_000), 0.4)).toBe(false);
+    expect(shouldBudgetFlush(usage(230_400, 256_000), 0.9)).toBe(true);
+    expect(shouldBudgetFlush(usage(230_399, 256_000), 0.9)).toBe(false);
+    expect(shouldBudgetFlush(usage(300_000, 300_000), 1)).toBe(true);
+  });
+
+  it("lets a low threshold govern below the ceiling on a huge window", () => {
+    expect(shouldBudgetFlush(usage(100_000, 1_000_000), 0.1)).toBe(true);
+    expect(shouldBudgetFlush(usage(99_999, 1_000_000), 0.1)).toBe(false);
+  });
 });
 
 describe("usageFraction", () => {
@@ -39,9 +62,14 @@ describe("usageFraction", () => {
     expect(usageFraction(usage(null, 1000))).toBeNull();
     expect(usageFraction(usage(900, 0))).toBeNull();
   });
-  it("returns the 0–1 fraction", () => {
+  it("returns the fraction against the effective window", () => {
     expect(usageFraction(usage(750, 1000))).toBe(0.75);
   });
+
+  it("is not clamped above 1 when the window exceeds the ceiling", () => {
+    expect(usageFraction(usage(600_000, 1_000_000))).toBe(2);
+    expect(usageFraction(usage(80_000, 200_000))).toBe(0.4);
+  });
 });
 
 describe("shouldDeltaFlush", () => {
@@ -63,4 +91,23 @@ describe("shouldDeltaFlush", () => {
     expect(shouldDeltaFlush(usage(640, 1000), 0.5, 0.15)).toBe(false); // 0.14 < 0.15
     expect(shouldDeltaFlush(usage(600, 1000), 0.5, 0.15)).toBe(false); // 0.10 < 0.15
   });
+
+  it("measures growth against the capped window on a huge-window model", () => {
+    // previousFraction for 100k tokens on a 1M window = 100_000 / 300_000
+    const prev = 100_000 / MAX_BUDGET_WINDOW;
+    expect(shouldDeltaFlush(usage(130_000, 1_000_000), prev, 0.1)).toBe(true);
+    expect(shouldDeltaFlush(usage(120_000, 1_000_000), prev, 0.1)).toBe(false);
+  });
+
+  it("leaves the growth requirement unchanged at or below the ceiling", () => {
+    const prev = 40_000 / 200_000; // 0.2
+    expect(shouldDeltaFlush(usage(100_000, 200_000), prev, 0.3)).toBe(true);  // +60k
+    expect(shouldDeltaFlush(usage(99_000, 200_000), prev, 0.3)).toBe(false);  // +59k
+  });
+
+  it("keeps re-arming above the ceiling, where the fraction exceeds 1", () => {
+    const prev = 600_000 / MAX_BUDGET_WINDOW; // 2.0 - unclamped by design
+    expect(shouldDeltaFlush(usage(630_000, 1_000_000), prev, 0.1)).toBe(true);
+    expect(shouldDeltaFlush(usage(620_000, 1_000_000), prev, 0.1)).toBe(false);
+  });
 });

package/src/budget.ts

@@ -1,10 +1,18 @@
 import type { ContextUsage } from "@earendil-works/pi-coding-agent";
 
+// Ceiling on what the budget triggers treat as the context window. Advertised
+// windows reach 1M, which makes any (0,1] fraction unreachable in a real session.
+// The two triggers apply it in different shapes on purpose: the threshold is a
+// LEVEL, so the cap bounds the level itself (min(CAP, threshold * window)); the
+// delta is a GROWTH RATE, where a 300k ceiling could never bind, so the cap
+// enters through the denominator instead (delta * min(window, CAP)).
+export const MAX_BUDGET_WINDOW = 300_000;
+
 /**
- * True iff a budget-triggered flush should fire. Computes the ratio ourselves
- * (tokens / contextWindow, a 0–1 fraction) rather than using ContextUsage.percent
- * (a 0–100 value, null when tokens is null). tokens is also null right after a
- * compaction — guarded here.
+ * True iff a budget-triggered flush should fire: at `threshold` of the model's
+ * window, or at MAX_BUDGET_WINDOW tokens, whichever comes first. Computes the
+ * level ourselves rather than using ContextUsage.percent (a 0–100 value, null
+ * when tokens is null). tokens is also null right after a compaction — guarded here.
  */
 export function shouldBudgetFlush(
   usage: ContextUsage | undefined,
@@ -12,17 +20,23 @@ export function shouldBudgetFlush(
 ): boolean {
   if (threshold == null || threshold <= 0 || threshold > 1) return false;
   if (!usage || usage.tokens == null || !(usage.contextWindow > 0)) return false;
-  return usage.tokens / usage.contextWindow >= threshold;
+  return usage.tokens >= Math.min(MAX_BUDGET_WINDOW, threshold * usage.contextWindow);
 }
 
-/** 0–1 usage fraction, or null when usage is missing / tokens null / window non-positive. */
+/**
+ * Usage fraction against the effective window (min(contextWindow, MAX_BUDGET_WINDOW)),
+ * or null when usage is missing / tokens null / window non-positive. NOT bounded by 1:
+ * 600k tokens on a 1M window returns 2.0. Deliberately unclamped — clamping would make
+ * shouldDeltaFlush saturate above the ceiling and stop re-arming.
+ */
 export function usageFraction(usage: ContextUsage | undefined): number | null {
   if (!usage || usage.tokens == null || !(usage.contextWindow > 0)) return null;
-  return usage.tokens / usage.contextWindow;
+  return usage.tokens / Math.min(usage.contextWindow, MAX_BUDGET_WINDOW);
 }
 
 /**
- * True iff this turn's usage fraction rose by at least `delta` versus the previous turn.
+ * True iff this turn's usage fraction rose by at least `delta` versus the previous turn,
+ * i.e. growth of at least `delta * min(contextWindow, MAX_BUDGET_WINDOW)` tokens.
  * Mirrors shouldBudgetFlush's guards. previousFraction === null (first turn or post-restart)
  * never fires; the absolute autoBudgetThreshold covers that gap.
  */

package/src/commands.ts

@@ -24,6 +24,7 @@ import {
 } from "./types.js";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { saveConfig } from "./config.js";
+import { MAX_BUDGET_WINDOW } from "./budget.js";
 import { formatTokens, formatCost, formatCharProgress, formatCompactCount } from "./stats.js";
 import { Container, Text, SettingsList, type SettingItem } from "@earendil-works/pi-tui";
 import { DynamicBorder, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
@@ -234,10 +235,12 @@ function maxTimeoutDescription(config: ContextPruneConfig): string {
 }
 
 function autoBudgetThresholdDescription(config: ContextPruneConfig): string {
+  const cap = `${MAX_BUDGET_WINDOW / 1000}k`;
   if (config.autoBudgetThreshold == null) {
-    return `Token-budget auto-flush: force a prune when context usage reaches this share of the window, regardless of prune-on mode. Currently off. Pick a percentage to enable.`;
+    return `Token-budget auto-flush: force a prune when context usage reaches this share of the window (or ${cap} tokens, whichever comes first), regardless of prune-on mode. Currently off. Pick a percentage to enable.`;
   }
-  return `Token-budget auto-flush: force a prune when context usage reaches ${Math.round(config.autoBudgetThreshold * 100)}% of the window, regardless of prune-on mode. Set to Off to disable.`;
+  const pct = Math.round(config.autoBudgetThreshold * 100);
+  return `Token-budget auto-flush: force a prune when context usage reaches ${pct}% of the window or ${cap} tokens, whichever comes first, regardless of prune-on mode. The ${cap} ceiling keeps this reachable on huge-window models. Set to Off to disable.`;
 }
 
 function protectedToolsDisplay(list: string[]): string {

package/src/types.ts

@@ -239,7 +239,8 @@ export const SUMMARIZER_MAX_TIMEOUT_PRESETS: { value: string; label: string }[]
 /**
  * Cycling presets for the `autoBudgetThreshold` setting (stored as strings;
  * the settings UI cycles string values). "0" is the disabled sentinel → null.
- * Other values are 0–1 fractions of the context window (e.g. "0.8" = flush at 80%).
+ * Other values are 0–1 fractions of the context window (e.g. "0.8" = flush at
+ * 80% of the window, or at MAX_BUDGET_WINDOW tokens, whichever comes first).
  */
 export const AUTO_BUDGET_PRESETS: { value: string; label: string }[] = [
   { value: "0", label: "Off (default)" },
@@ -387,10 +388,14 @@ export interface ContextPruneConfig {
   /**
    * Token-budget auto-flush trigger. A fraction in (0, 1] (a 0–1 share of the
    * context window, NOT a 0–100 percentage; e.g. 0.8 = flush at 80% of the
-   * window). When set, a flush of all pending batches is forced at the end of
-   * any tool-using turn once context usage (tokens / contextWindow) reaches the
-   * threshold — regardless of `pruneOn`. An ADDITIONAL trigger on top of
-   * `pruneOn`, not a replacement.
+   * window, capped at 300k tokens - see below). When set, a flush of all
+   * pending batches is forced at the end of
+   * any tool-using turn once context usage reaches `threshold * contextWindow`
+   * tokens OR 300,000 tokens (MAX_BUDGET_WINDOW in src/budget.ts), whichever
+   * comes first — regardless of `pruneOn`. The ceiling keeps the setting
+   * reachable on huge-window models, where 0.9 of 1M would mean 900k tokens; it
+   * never binds on a model advertising 300k or less. An ADDITIONAL trigger on
+   * top of `pruneOn`, not a replacement.
    *
    * null (default) = disabled, preserving pre-feature behavior. Out-of-range
    * values (<= 0 or > 1) normalize to null.
@@ -402,7 +407,11 @@ export interface ContextPruneConfig {
   spillPreviewBytes: number;
   /**
    * Per-turn usage-fraction increase (0–1) that forces a flush, independent of
-   * autoBudgetThreshold. null (default) = disabled. Out-of-range (<= 0 or > 1) normalizes to null.
+   * autoBudgetThreshold. The fraction is measured against the effective window
+   * `min(contextWindow, MAX_BUDGET_WINDOW)` (300_000), so the required growth is
+   * `delta * min(contextWindow, MAX_BUDGET_WINDOW)` tokens - e.g. 0.1 means +30k
+   * tokens in one turn on any model at or above 300k, and +20k on a 200k model.
+   * null (default) = disabled. Out-of-range (<= 0 or > 1) normalizes to null.
    */
   budgetTurnDelta: number | null;
 }