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.
- package/README.md +24 -7
- package/index.ts +21 -130
- 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
|
|
282
|
-
r=0.25, T=54 at r=0.5, T=58
|
|
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
|
|
394
|
-
|
|
395
|
-
|
|
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
|
|
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
|
-
*
|
|
291
|
-
*
|
|
292
|
-
*
|
|
293
|
-
*
|
|
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.
|
|
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
|
-
*
|
|
497
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
2424
|
-
|
|
2425
|
-
|
|
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,
|