pi-dynamic-context-pruning 0.1.13 → 0.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +24 -7
  2. package/index.ts +21 -130
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -275,11 +275,21 @@ Notes:
275
275
  warm request prefix between consecutive LLM calls separated only by a
276
276
  toolResult) illustrates cache invalidation, not proof that amortization is
277
277
  impossible. Set `mid_loop` back to `22` to restore the old parity behavior.
278
+ - `gate.breakEvenThreshold` is a deprecated legacy field retained for
279
+ compatibility. Loaded config always resolves through
280
+ `gate.breakEvenThresholdByState`, so a global-only value (including `0`) has
281
+ no runtime effect, and missing or invalid state values use their existing
282
+ normalized defaults rather than inheriting the global value. Direct callers
283
+ of the exported `resolveBreakEvenThreshold` may still use this field as the
284
+ fallback when they pass an unnormalized gate object. Set explicit per-state
285
+ values instead.
278
286
  - `gate.breakEvenThreshold`'s default of `22` is calibrated from the
279
287
  representative-corpus benchmark at `cachedPriceRatio` r=0.1 (aggressive
280
288
  prompt caching, the common case). It is **provider/ratio-
281
- dependent**: the optimal threshold rises as caching gets weaker (T=29 at
282
- r=0.25, T=54 at r=0.5, T=58 at r=0.9 on the same corpus).
289
+ dependent**. In the **historical, retired turn-end run**, the optimal
290
+ threshold rose as caching got weaker (T=29 at r=0.25, T=54 at r=0.5, T=58
291
+ at r=0.9); these are not current turn-start results. See
292
+ [`docs/v2-design.md` §4](./docs/v2-design.md#4-benchmark-decision-gate).
283
293
 
284
294
  ## Prompt-cache trade-off
285
295
 
@@ -326,6 +336,8 @@ Options:
326
336
  - `--limit N`: only process the first N session files found.
327
337
  - `--ratio R`: cached-price ratio(s) to model; repeatable and/or
328
338
  comma-separated (e.g. `--ratio 0.1,0.2`). Default: `0.1`.
339
+ - `--sweep-max N`: explicit ceiling for the auto-expanding threshold sweep
340
+ (overrides the corpus-derived ceiling). Default: auto-expand from 30 as needed.
329
341
  - `--json`: emit a full machine-readable JSON dump instead of aligned text.
330
342
  - `--simulate-compression`: additionally SIMULATE v2-style range compression
331
343
  (docs/v2-design.md §1/§4 go/no-go evidence) alongside — never mixed into —
@@ -390,9 +402,11 @@ reports two kinds of numbers:
390
402
  prune point, and the *actual* net benefit that prune would have produced —
391
403
  `realizedNetBenefit = actualRemainingCalls * recurringSaving - penalty`.
392
404
 
393
- It also sweeps the break-even threshold `T` from 1 to 30 and reports the `T`
394
- that maximizes total realized net benefit across all gate-eligible
395
- candidates, both overall and split by idle/mid-loop agent state.
405
+ It also sweeps the break-even threshold `T` from 1 to 30, then keeps doubling
406
+ the range while the best `T` sits at the top edge, up to a corpus-derived
407
+ ceiling (hard cap 500). `--sweep-max N` sets that ceiling explicitly. It
408
+ reports the `T` that maximizes total realized net benefit across all
409
+ gate-eligible candidates, both overall and split by idle/mid-loop agent state.
396
410
 
397
411
  ## Comparison
398
412
 
@@ -428,9 +442,11 @@ net benefit, at sufficient candidate volume, with enough remaining-calls
428
442
  runway per session to plausibly amortize a compression summary's own token
429
443
  cost — see `docs/v2-design.md` §4 for the exact go/no-go bar.
430
444
 
431
- The representative-corpus run of the benchmark harness (over
445
+ The **historical, retired turn-end run** of the benchmark harness (over
432
446
  `~/.the-last-harness/agent/sessions`: 1,390+ session files, 556 gate-eligible
433
- candidates — see the corpus-choice note above) produced:
447
+ candidates — see the corpus-choice note above) produced the following
448
+ figures, preserved as historical context rather than current turn-start
449
+ results (see [`docs/v2-design.md` §4](./docs/v2-design.md#4-benchmark-decision-gate)):
434
450
 
435
451
  - **Candidates and tokens removed by strategy**: `dedupe` 111 candidates /
436
452
  93,330 tokens removed; `error-purge` 187 / 28,191; `superseded-file-ops`
@@ -440,6 +456,7 @@ candidates — see the corpus-choice note above) produced:
440
456
  this corpus is dominated by long, tool-heavy agent sessions rather than
441
457
  short orchestrator sessions.
442
458
 
459
+ The current turn-start re-derivation has 460 gate-eligible candidates.
443
460
  Shipped gate defaults remain `idle=22` / `mid_loop=1` (see
444
461
  [Configuration](#configuration)).
445
462
 
package/index.ts CHANGED
@@ -140,12 +140,6 @@ export function normalizeSessionProjection(value: unknown): MinimalSessionProjec
140
140
  return { entries, messages: entries.flatMap((entry) => entry.messages) };
141
141
  }
142
142
 
143
- export function sessionProjectionToMessages(
144
- projection: MinimalSessionProjection,
145
- ): MinimalMessage[] {
146
- return projection.entries.flatMap((entry) => entry.messages);
147
- }
148
-
149
143
  const EXTENSION_ID = "dynamic-context-pruning";
150
144
  const CONFIG_FILE_NAME = "dynamic-context-pruning.json";
151
145
  const DECISION_ENTRY_TYPE = "dynamic-context-pruning:decision";
@@ -164,37 +158,10 @@ const DEFAULT_RECENT_TURNS = 4;
164
158
  /** Cache cost model default: fraction of full (non-cached) price still paid for cached tokens. */
165
159
  const DEFAULT_CACHED_PRICE_RATIO = 0.1;
166
160
 
167
- /**
168
- * Default net-benefit gate threshold (max amortization calls). Recalibrated
169
- * from the representative-corpus benchmark (~/.the-last-harness/
170
- * agent/sessions, 1,390+ session files, 556 candidates): this is the
171
- * hindsight-optimal break-even T at cachedPriceRatio r=0.1 (aggressive
172
- * prompt caching, the common Anthropic case). IMPORTANT caveats:
173
- * - Provider/ratio-dependent: this optimum shifts higher as caching gets
174
- * weaker (T=29 at r=0.25, T=54 at r=0.5, T=58 at r=0.9 on the same
175
- * corpus) — see docs/v2-design.md section 4 and the extension README.
176
- * - At r=0.1 the realized deterministic savings this threshold buys are
177
- * economically marginal (~20.6k token-units total across the whole
178
- * corpus, i.e. pennies); savings only become material at r>=0.25.
179
- * - Re-derive via `scripts/benchmark.mjs <sessions-dir> --ratio 0.1` if
180
- * the representative corpus changes meaningfully.
181
- */
161
+ /** Default idle net-benefit gate threshold; see README.md and docs/v2-design.md §4. */
182
162
  const DEFAULT_BREAK_EVEN_THRESHOLD = 22;
183
163
 
184
- /**
185
- * Default mid_loop break-even threshold. The package's own
186
- * representative-corpus benchmark (turn-START state definition — the same one
187
- * the runtime `context` handler uses) favored rejecting mid_loop candidates
188
- * at cachedPriceRatio r=0.1 (mid_loop-optimal T=1, total realized
189
- * net benefit ~0.0). This supports a conservative default for the measured
190
- * corpus, not a universal claim that mid_loop pruning cannot pay off.
191
- * The reported 2026-09-08 byte-level capture (a mid_loop prune at T=22
192
- * invalidating 81% of a warm request prefix) illustrates cache invalidation,
193
- * not an inability to amortize it: enough subsequent calls can recoup a
194
- * one-time bust. Idle keeps T=22; turn-start classification does not imply
195
- * the provider cache is cold. Users who want the old behavior can override
196
- * via gate.breakEvenThresholdByState.mid_loop.
197
- */
164
+ /** Default mid_loop threshold; see README.md for the runtime-aligned benchmark rationale. */
198
165
  const DEFAULT_MID_LOOP_BREAK_EVEN_THRESHOLD = 1;
199
166
 
200
167
  /** Tool names never pruned by default: orchestration/subagent-style tools and todo-like state. */
@@ -243,18 +210,7 @@ export interface PruneProtections {
243
210
  }
244
211
 
245
212
  export interface PruneThresholds {
246
- /**
247
- * Minimum raw text characters a fresh AUTOMATIC prune proposal must remove
248
- * (original text chars minus placeholder chars) to be considered at all
249
- * Enforced by `runDynamicContextPruningPipeline` BEFORE the
250
- * net-benefit gate (see `PruneGateConfig`/`gate`, which uses break-even token
251
- * math and is a separate, later check): text-only candidates below this floor
252
- * are dropped up front and never reach gate/batch consideration. Image-bearing
253
- * tool-result candidates bypass this raw-text floor (images receive no
254
- * synthetic character count) and proceed to the token-based gate. Manual
255
- * prunes and already-persisted/replayed decisions always bypass this floor,
256
- * same as the gate. A value of 0 disables the floor (no filtering).
257
- */
213
+ /** Minimum automatic-prune text saving; see README.md Configuration for bypass rules. */
258
214
  minCharsSaved: number;
259
215
  }
260
216
 
@@ -287,13 +243,15 @@ export interface PruneGateConfig {
287
243
  /** Fraction of full price still paid for cached ( r ). Default 0.1. */
288
244
  cachedPriceRatio: number;
289
245
  /**
290
- * Default break-even threshold (max future calls to amortize a cache
291
- * bust) used when no state-specific override applies. Recalibrated from
292
- * the representative-corpus benchmark; see DEFAULT_BREAK_EVEN_THRESHOLD
293
- * for the full rationale and ratio-sensitivity caveats.
246
+ * @deprecated Legacy global fallback retained for direct callers that pass
247
+ * an unnormalized gate object to resolveBreakEvenThreshold. normalizeConfig
248
+ * always supplies per-state values, so loaded config does not use this field
249
+ * to fill missing or invalid state values. Recalibrated from the
250
+ * representative-corpus benchmark; see DEFAULT_BREAK_EVEN_THRESHOLD for the
251
+ * full rationale and ratio-sensitivity caveats.
294
252
  */
295
253
  breakEvenThreshold: number;
296
- /** Per-state overrides. Defaults: idle 22, mid_loop 1. */
254
+ /** Per-state overrides. normalizeConfig defaults to idle 22 and mid_loop 1. */
297
255
  breakEvenThresholdByState: { idle: number; mid_loop: number };
298
256
  }
299
257
 
@@ -493,29 +451,8 @@ export function estimateTokensForContent(
493
451
  export type TokenEstimator = (text: string) => number;
494
452
 
495
453
  /**
496
- * Classify the agent's current state from the message payload alone:
497
- * this is the runtime-observable definition used both by the live `context`
498
- * event handler and (via re-export) by the offline benchmark, so the two can
499
- * never drift apart.
500
- *
501
- * Walk backwards from the end of `messages`, skipping any message that is
502
- * neither `user`, `assistant`, nor `toolResult` (e.g. system-role bookkeeping
503
- * entries). The first such message found determines the state:
504
- * - `user` (a plain user turn message) => "idle": this call is the FIRST LLM
505
- * call of a turn, i.e. the decision is being made from a turn-start state.
506
- * - `assistant` or `toolResult` (mid-chain) => "mid_loop": the agent is
507
- * iterating (already made at least one call this turn, or is reacting to a
508
- * tool result).
509
- * - No such message found (empty history, or system-only) => "idle" (safe
510
- * default: nothing suggests an in-progress loop).
511
- *
512
- * The benchmark (scripts/benchmark.mjs) reclassifies its candidate labels to
513
- * this SAME definition, reusing this function directly, so the
514
- * defaults below rest on evidence measured with the exact definition the
515
- * runtime observes. (An earlier turn-end-based benchmark definition -- "idle"
516
- * meant "this IS the turn's last assistant message", only knowable in
517
- * hindsight -- has been retired: the runtime cannot know in advance whether a
518
- * call is a turn's last one, so that definition was never runtime-observable.)
454
+ * Shared runtime/benchmark state classifier; see README.md Configuration and
455
+ * docs/v2-design.md §4 for the turn-start definition and retired turn-end analysis.
519
456
  */
520
457
  export function classifyAgentStateFromMessages(messages: MinimalMessage[]): AgentState {
521
458
  for (let i = messages.length - 1; i >= 0; i--) {
@@ -677,7 +614,7 @@ export function isWithinRecencyWindow(index: number, boundaryIndex: number): boo
677
614
  * Used by the error-input purge strategy's "older than N turns" rule; a
678
615
  * message at the very end of the conversation has 0 turns elapsed.
679
616
  */
680
- export function computeTurnsElapsedSince(messages: MinimalMessage[], index: number): number {
617
+ function computeTurnsElapsedSince(messages: MinimalMessage[], index: number): number {
681
618
  let count = 0;
682
619
  for (let i = index + 1; i < messages.length; i++) {
683
620
  if (messages[i].role === "user") count++;
@@ -974,7 +911,7 @@ export function resolvePruneTombstoneState(entries: MinimalSessionEntry[]): Prun
974
911
  return { activeDecisions, activeIdempotencyKeys, restoredKeys, lastDecisionByKey };
975
912
  }
976
913
 
977
- export function buildPlaceholderText(reason: string, charsRemoved: number): string {
914
+ function buildPlaceholderText(reason: string, charsRemoved: number): string {
978
915
  return `[pruned by ${EXTENSION_ID}: ${reason} (${charsRemoved} chars removed)]`;
979
916
  }
980
917
 
@@ -1581,7 +1518,7 @@ export function collectCompletedToolCallOccurrences(
1581
1518
  }
1582
1519
 
1583
1520
  /** Placeholder text for a duplicate tool result whose content was replaced. */
1584
- export function buildDedupePlaceholder(toolName: string, newestToolCallId: string): string {
1521
+ function buildDedupePlaceholder(toolName: string, newestToolCallId: string): string {
1585
1522
  return `[pruned by ${EXTENSION_ID}: duplicate ${toolName} call result; see newest occurrence (call ${newestToolCallId})]`;
1586
1523
  }
1587
1524
 
@@ -1642,46 +1579,6 @@ export const errorPurgeStrategy: PruneStrategy = {
1642
1579
  },
1643
1580
  };
1644
1581
 
1645
- // When the same file path is read and/or written multiple times in a
1646
- // session, older read/write/edit tool *outputs* for that path can become
1647
- // stale relative to a later operation. This strategy proposes replacing
1648
- // those older outputs with a placeholder, per the following CONSERVATIVE,
1649
- // binding rules (do not loosen without an architect decision):
1650
- //
1651
- // 1. A full-file read (no offset/limit args) is superseded by a LATER
1652
- // full-file read of the same normalized path.
1653
- // 2. A partial read (offset/limit args present) is NOT superseded by a
1654
- // later partial read UNLESS the later read's range fully covers the
1655
- // earlier one's range. If range coverage can't be reliably determined
1656
- // from the args (e.g. earlier read has no limit — reads to EOF — but
1657
- // the later read is bounded), skip: do not propose supersession.
1658
- // Full-file reads are represented as the range [1, EOF); comparing
1659
- // that representation via the same coverage check naturally satisfies
1660
- // rule 1 as a special case of rule 2 (see `readRangeCovers`).
1661
- // 3. ANY read of a path (full or partial) is superseded once a LATER
1662
- // *successful* (non-error) write/edit to that same path occurs — the
1663
- // old read output is now known-stale regardless of read-vs-read range
1664
- // comparisons. The placeholder explicitly notes the file has since
1665
- // changed. An ERRORED later write/edit does NOT count (the file may be
1666
- // unchanged; conservative).
1667
- // 4. Older write/edit outputs for a path are superseded by a LATER
1668
- // *successful* write/edit to that same path (again, a later errored
1669
- // write/edit never supersedes). Write/edit tool outputs are usually
1670
- // small, so proposals are only ever emitted when there is a non-empty
1671
- // result to prune; the shared net-benefit gate additionally decides
1672
- // whether the estimated savings are worth the cache-bust cost.
1673
- //
1674
- // The NEWEST operation for a given path (by message order) is never
1675
- // superseded/pruned, regardless of kind — there is nothing later to point
1676
- // the placeholder at.
1677
- //
1678
- // Path extraction is defensive: pi's built-in `read`/`write`/`edit` tools
1679
- // all accept a `path` argument (see packages/coding-agent/src/core/tools/
1680
- // {read,write,edit}.ts); some tool-call renderers also fall back to a
1681
- // legacy `file_path` name, and `filePath` is accepted as a further
1682
- // defensive fallback. `bash` is explicitly OUT of scope: this strategy does
1683
- // not attempt to parse shell commands for file paths.
1684
-
1685
1582
  const SUPERSEDED_FILE_OPS_STRATEGY_ID = "superseded-file-ops";
1686
1583
 
1687
1584
  type FileOpKind = "read" | "write" | "edit";
@@ -1736,11 +1633,6 @@ export function computeFileReadRange(args: Record<string, unknown> | undefined):
1736
1633
  return { start, end };
1737
1634
  }
1738
1635
 
1739
- /** True when a range represents a full-file read (starts at line 1, no limit). */
1740
- export function isFullFileReadRange(range: FileReadRange): boolean {
1741
- return range.start === 1 && range.end === undefined;
1742
- }
1743
-
1744
1636
  /**
1745
1637
  * Conservative range-coverage check: does `later` fully cover `earlier`?
1746
1638
  * Implements rules 1+2 above via one unified representation (a full-file
@@ -2234,7 +2126,7 @@ export function sessionEntriesToMessages(
2234
2126
  entries: MinimalSessionEntry[],
2235
2127
  projection?: MinimalSessionProjection,
2236
2128
  ): MinimalMessage[] {
2237
- if (projection) return sessionProjectionToMessages(projection);
2129
+ if (projection) return projection.entries.flatMap((entry) => entry.messages);
2238
2130
  const messages: MinimalMessage[] = [];
2239
2131
  for (const entry of entries) {
2240
2132
  if (entry.type === "message" && entry.message) messages.push(entry.message);
@@ -2373,11 +2265,9 @@ const STRATEGY_ALIASES: Record<string, StrategyKey> = {
2373
2265
  "error-purge": "errorPurge",
2374
2266
  errorpurge: "errorPurge",
2375
2267
  error_purge: "errorPurge",
2376
- errorPurge: "errorPurge",
2377
2268
  "superseded-file-ops": "supersededFileOps",
2378
2269
  supersededfileops: "supersededFileOps",
2379
2270
  superseded_file_ops: "supersededFileOps",
2380
- supersededFileOps: "supersededFileOps",
2381
2271
  };
2382
2272
 
2383
2273
  const STRATEGY_DISPLAY_NAMES: Record<StrategyKey, string> = {
@@ -2420,9 +2310,11 @@ export function parseContextPruningArgs(rawArgs: string): ContextPruningSubcomma
2420
2310
  return { kind: "toggle" };
2421
2311
  case "strategy": {
2422
2312
  const [nameRaw, valueRaw] = rest;
2423
- const key = nameRaw
2424
- ? (STRATEGY_ALIASES[nameRaw.toLowerCase()] ?? STRATEGY_ALIASES[nameRaw])
2425
- : undefined;
2313
+ const normalizedName = nameRaw?.toLowerCase();
2314
+ const key =
2315
+ normalizedName && Object.hasOwn(STRATEGY_ALIASES, normalizedName)
2316
+ ? STRATEGY_ALIASES[normalizedName]
2317
+ : undefined;
2426
2318
  const value = valueRaw?.toLowerCase();
2427
2319
  if (!key || (value !== "on" && value !== "off")) return { kind: "unknown", raw: rawArgs };
2428
2320
  return { kind: "strategy", strategy: key, value: value === "on" };
@@ -2568,7 +2460,6 @@ function notify(
2568
2460
  }
2569
2461
 
2570
2462
  export const __testing = {
2571
- globToRegExp,
2572
2463
  getConfigPath,
2573
2464
  readConfig,
2574
2465
  writeConfig,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-dynamic-context-pruning",
3
- "version": "0.1.13",
3
+ "version": "0.1.15",
4
4
  "type": "module",
5
5
  "description": "A pi extension that dynamically prunes stale context to keep sessions lean.",
6
6
  "keywords": [