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.
- package/README.md +16 -7
- package/index.ts +9 -114
- 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
|
|
282
|
-
r=0.25, T=54 at r=0.5, T=58
|
|
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
|
|
394
|
-
|
|
395
|
-
|
|
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
|
|
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
|
-
*
|
|
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.)
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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);
|