pi-dynamic-context-pruning 0.1.13 → 0.1.14

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 +16 -7
  2. package/index.ts +9 -114
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -278,8 +278,10 @@ Notes:
278
278
  - `gate.breakEvenThreshold`'s default of `22` is calibrated from the
279
279
  representative-corpus benchmark at `cachedPriceRatio` r=0.1 (aggressive
280
280
  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).
281
+ dependent**. In the **historical, retired turn-end run**, the optimal
282
+ threshold rose as caching got weaker (T=29 at r=0.25, T=54 at r=0.5, T=58
283
+ at r=0.9); these are not current turn-start results. See
284
+ [`docs/v2-design.md` §4](./docs/v2-design.md#4-benchmark-decision-gate).
283
285
 
284
286
  ## Prompt-cache trade-off
285
287
 
@@ -326,6 +328,8 @@ Options:
326
328
  - `--limit N`: only process the first N session files found.
327
329
  - `--ratio R`: cached-price ratio(s) to model; repeatable and/or
328
330
  comma-separated (e.g. `--ratio 0.1,0.2`). Default: `0.1`.
331
+ - `--sweep-max N`: explicit ceiling for the auto-expanding threshold sweep
332
+ (overrides the corpus-derived ceiling). Default: auto-expand from 30 as needed.
329
333
  - `--json`: emit a full machine-readable JSON dump instead of aligned text.
330
334
  - `--simulate-compression`: additionally SIMULATE v2-style range compression
331
335
  (docs/v2-design.md §1/§4 go/no-go evidence) alongside — never mixed into —
@@ -390,9 +394,11 @@ reports two kinds of numbers:
390
394
  prune point, and the *actual* net benefit that prune would have produced —
391
395
  `realizedNetBenefit = actualRemainingCalls * recurringSaving - penalty`.
392
396
 
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.
397
+ It also sweeps the break-even threshold `T` from 1 to 30, then keeps doubling
398
+ the range while the best `T` sits at the top edge, up to a corpus-derived
399
+ ceiling (hard cap 500). `--sweep-max N` sets that ceiling explicitly. It
400
+ reports the `T` that maximizes total realized net benefit across all
401
+ gate-eligible candidates, both overall and split by idle/mid-loop agent state.
396
402
 
397
403
  ## Comparison
398
404
 
@@ -428,9 +434,11 @@ net benefit, at sufficient candidate volume, with enough remaining-calls
428
434
  runway per session to plausibly amortize a compression summary's own token
429
435
  cost — see `docs/v2-design.md` §4 for the exact go/no-go bar.
430
436
 
431
- The representative-corpus run of the benchmark harness (over
437
+ The **historical, retired turn-end run** of the benchmark harness (over
432
438
  `~/.the-last-harness/agent/sessions`: 1,390+ session files, 556 gate-eligible
433
- candidates — see the corpus-choice note above) produced:
439
+ candidates — see the corpus-choice note above) produced the following
440
+ figures, preserved as historical context rather than current turn-start
441
+ results (see [`docs/v2-design.md` §4](./docs/v2-design.md#4-benchmark-decision-gate)):
434
442
 
435
443
  - **Candidates and tokens removed by strategy**: `dedupe` 111 candidates /
436
444
  93,330 tokens removed; `error-purge` 187 / 28,191; `superseded-file-ops`
@@ -440,6 +448,7 @@ candidates — see the corpus-choice note above) produced:
440
448
  this corpus is dominated by long, tool-heavy agent sessions rather than
441
449
  short orchestrator sessions.
442
450
 
451
+ The current turn-start re-derivation has 460 gate-eligible candidates.
443
452
  Shipped gate defaults remain `idle=22` / `mid_loop=1` (see
444
453
  [Configuration](#configuration)).
445
454
 
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
 
@@ -493,29 +449,8 @@ export function estimateTokensForContent(
493
449
  export type TokenEstimator = (text: string) => number;
494
450
 
495
451
  /**
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.)
452
+ * Shared runtime/benchmark state classifier; see README.md Configuration and
453
+ * docs/v2-design.md §4 for the turn-start definition and retired turn-end analysis.
519
454
  */
520
455
  export function classifyAgentStateFromMessages(messages: MinimalMessage[]): AgentState {
521
456
  for (let i = messages.length - 1; i >= 0; i--) {
@@ -677,7 +612,7 @@ export function isWithinRecencyWindow(index: number, boundaryIndex: number): boo
677
612
  * Used by the error-input purge strategy's "older than N turns" rule; a
678
613
  * message at the very end of the conversation has 0 turns elapsed.
679
614
  */
680
- export function computeTurnsElapsedSince(messages: MinimalMessage[], index: number): number {
615
+ function computeTurnsElapsedSince(messages: MinimalMessage[], index: number): number {
681
616
  let count = 0;
682
617
  for (let i = index + 1; i < messages.length; i++) {
683
618
  if (messages[i].role === "user") count++;
@@ -974,7 +909,7 @@ export function resolvePruneTombstoneState(entries: MinimalSessionEntry[]): Prun
974
909
  return { activeDecisions, activeIdempotencyKeys, restoredKeys, lastDecisionByKey };
975
910
  }
976
911
 
977
- export function buildPlaceholderText(reason: string, charsRemoved: number): string {
912
+ function buildPlaceholderText(reason: string, charsRemoved: number): string {
978
913
  return `[pruned by ${EXTENSION_ID}: ${reason} (${charsRemoved} chars removed)]`;
979
914
  }
980
915
 
@@ -1581,7 +1516,7 @@ export function collectCompletedToolCallOccurrences(
1581
1516
  }
1582
1517
 
1583
1518
  /** Placeholder text for a duplicate tool result whose content was replaced. */
1584
- export function buildDedupePlaceholder(toolName: string, newestToolCallId: string): string {
1519
+ function buildDedupePlaceholder(toolName: string, newestToolCallId: string): string {
1585
1520
  return `[pruned by ${EXTENSION_ID}: duplicate ${toolName} call result; see newest occurrence (call ${newestToolCallId})]`;
1586
1521
  }
1587
1522
 
@@ -1642,46 +1577,6 @@ export const errorPurgeStrategy: PruneStrategy = {
1642
1577
  },
1643
1578
  };
1644
1579
 
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
1580
  const SUPERSEDED_FILE_OPS_STRATEGY_ID = "superseded-file-ops";
1686
1581
 
1687
1582
  type FileOpKind = "read" | "write" | "edit";
@@ -2234,7 +2129,7 @@ export function sessionEntriesToMessages(
2234
2129
  entries: MinimalSessionEntry[],
2235
2130
  projection?: MinimalSessionProjection,
2236
2131
  ): MinimalMessage[] {
2237
- if (projection) return sessionProjectionToMessages(projection);
2132
+ if (projection) return projection.entries.flatMap((entry) => entry.messages);
2238
2133
  const messages: MinimalMessage[] = [];
2239
2134
  for (const entry of entries) {
2240
2135
  if (entry.type === "message" && entry.message) messages.push(entry.message);
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.14",
4
4
  "type": "module",
5
5
  "description": "A pi extension that dynamically prunes stale context to keep sessions lean.",
6
6
  "keywords": [