pi-dynamic-context-pruning 0.1.8 → 0.1.10

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 +25 -16
  2. package/index.ts +146 -29
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -130,10 +130,10 @@ Where `r` is `gate.cachedPriceRatio` — the fraction of full price still paid
130
130
  for cached tokens (default `0.1`, i.e. cached tokens cost ~10% of fresh
131
131
  tokens). `breakEvenCalls` is how many subsequent LLM calls are needed to
132
132
  recoup the one-time cache-bust cost via the recurring saving. The gate accepts
133
- a batch of candidates only if `breakEvenCalls <= gate.breakEvenThreshold`
134
- (default `22`, calibrated from the representative-corpus benchmark — see the
135
- calibration note under [Configuration](#configuration) and the
136
- [Roadmap](#roadmap) evidence).
133
+ a batch of candidates only if `breakEvenCalls` is at most the effective
134
+ threshold for the current state (`idle=22`, `mid_loop=1` by default,
135
+ calibrated from the representative-corpus benchmark — see the calibration
136
+ note under [Configuration](#configuration) and the [Roadmap](#roadmap) evidence).
137
137
 
138
138
  All candidates proposed in the same `context` call share one cache bust (since
139
139
  a prompt cache is a single linear prefix), so they're evaluated and
@@ -154,7 +154,7 @@ Gate modes (`/context-pruning gate <mode>`):
154
154
  ### `/prune`
155
155
 
156
156
  Interactive picker (TUI/RPC) over every prunable tool result in the current
157
- branch:
157
+ model context:
158
158
 
159
159
  ```text
160
160
  /prune
@@ -179,7 +179,7 @@ branch:
179
179
  /context-pruning gate <on|off|always-apply>
180
180
  ```
181
181
 
182
- - `status`: enabled state, gate mode/threshold/ratio, per-strategy on/off
182
+ - `status`: enabled state, gate mode/effective per-state thresholds/ratio, per-strategy on/off
183
183
  state, protection counts, last call's raw/effective/saved token snapshot,
184
184
  and current context usage.
185
185
  - `stats`: cumulative tokens saved, overall and per strategy.
@@ -223,7 +223,7 @@ never required to exist. Full shape, with defaults:
223
223
  "mode": "on",
224
224
  "cachedPriceRatio": 0.1,
225
225
  "breakEvenThreshold": 22,
226
- "breakEvenThresholdByState": { "idle": 22, "mid_loop": 22 }
226
+ "breakEvenThresholdByState": { "idle": 22, "mid_loop": 1 }
227
227
  }
228
228
  }
229
229
  ```
@@ -243,7 +243,8 @@ Notes:
243
243
  break-even math (`gate.*`), which is a separate, later check on whatever
244
244
  survives this floor.
245
245
  - `gate.breakEvenThresholdByState` lets `idle` vs `mid_loop` agent states use
246
- different thresholds; both default to `gate.breakEvenThreshold`. Real
246
+ different thresholds; `idle` defaults to `22` and
247
+ `mid_loop` defaults to `1`. Real
247
248
  mid-loop/idle detection is wired through the `context` event handler
248
249
  (pe-zy4s): the state is classified straight from the message payload —
249
250
  `idle` if the most recent relevant message is a user message (this is the
@@ -253,9 +254,15 @@ Notes:
253
254
  runtime-observable definition and found the state-split REVERSED from an
254
255
  earlier turn-end-based analysis: at r=0.1, `idle` candidates now carry
255
256
  essentially all the realized net benefit and `mid_loop` candidates carry
256
- essentially none. Since `idle` is not the worthless state under this
257
- definition, both states are kept at parity (`22`/`22`) rather than forcing
258
- a stricter default in either direction.
257
+ essentially none. At r=0.1, the measured corpus therefore supports a
258
+ conservative `mid_loop=1` default, while `idle` remains `22`. Mid-loop
259
+ pruning can amortize over enough subsequent calls, but the observed
260
+ candidates did not justify a more permissive threshold. Turn-start
261
+ classification does not imply the provider cache is cold. The reported
262
+ field capture (2026-09-08: a mid_loop prune at `T=22` invalidated 81% of a
263
+ warm request prefix between consecutive LLM calls separated only by a
264
+ toolResult) illustrates cache invalidation, not proof that amortization is
265
+ impossible. Set `mid_loop` back to `22` to restore the old parity behavior.
259
266
  - `gate.breakEvenThreshold`'s default of `22` is calibrated from the
260
267
  representative-corpus benchmark at `cachedPriceRatio` r=0.1 (aggressive
261
268
  prompt caching, the common case) — see [Roadmap](#roadmap) for the full
@@ -448,11 +455,13 @@ re-derived on the representative corpus (460 gate-eligible candidates on the
448
455
  current `~/.the-last-harness/agent/sessions` corpus). The split **reverses**:
449
456
  at r=0.1, `idle` (T=22, ~20.6k realized net benefit) now carries essentially
450
457
  all the value, and `mid_loop` (T=1, ~0 realized net benefit) carries
451
- essentially none. Per the decision rule (stricter idle default only if idle
452
- is shown ~worthless), this evidence does **not** support a stricter idle
453
- default — parity (`22`/`22`) is kept. The table above is retained as the
454
- historical turn-END-definition record; it no longer reflects how the runtime
455
- classifies agent state.
458
+ essentially none. Under that ticket's decision rule (stricter idle default
459
+ only if idle is shown ~worthless), parity (`22`/`22`) was retained at the time.
460
+ The 2026-09-08 follow-up supersedes that default with `idle=22` / `mid_loop=1`,
461
+ using the measured mid-loop result to choose a conservative threshold (see
462
+ [Configuration](#configuration) for the evidence and limitations). The table
463
+ above is retained as the historical turn-END-definition record; it no longer
464
+ reflects how the runtime classifies agent state.
456
465
 
457
466
  **This reframes, rather than weakens, the case for v2.** Small deterministic
458
467
  removals (dedupe/error-purge/superseded-file-ops) structurally cannot beat
package/index.ts CHANGED
@@ -75,6 +75,54 @@ export interface MinimalSessionEntry {
75
75
  [key: string]: unknown;
76
76
  }
77
77
 
78
+ export interface MinimalProjectedSessionEntry {
79
+ sourceEntry: MinimalSessionEntry;
80
+ messages: MinimalMessage[];
81
+ }
82
+
83
+ export interface MinimalSessionProjection {
84
+ entries: MinimalProjectedSessionEntry[];
85
+ messages?: MinimalMessage[];
86
+ }
87
+
88
+ function isRecord(value: unknown): value is Record<string, unknown> {
89
+ return typeof value === "object" && value !== null;
90
+ }
91
+
92
+ function isMinimalMessage(value: unknown): value is MinimalMessage {
93
+ return isRecord(value) && typeof value.role === "string" && value.role.length > 0;
94
+ }
95
+
96
+ function isProjectionSourceEntry(value: unknown): value is MinimalSessionEntry {
97
+ return isRecord(value)
98
+ && typeof value.type === "string"
99
+ && value.type.length > 0
100
+ && typeof value.id === "string"
101
+ && value.id.length > 0;
102
+ }
103
+
104
+ export function normalizeSessionProjection(value: unknown): MinimalSessionProjection | undefined {
105
+ if (!isRecord(value) || !Array.isArray(value.entries)) return undefined;
106
+
107
+ const entries: MinimalProjectedSessionEntry[] = [];
108
+ for (const candidate of value.entries) {
109
+ if (!isRecord(candidate) || !isProjectionSourceEntry(candidate.sourceEntry) || !Array.isArray(candidate.messages)) return undefined;
110
+ if (!candidate.messages.every(isMinimalMessage)) return undefined;
111
+ entries.push({
112
+ sourceEntry: candidate.sourceEntry,
113
+ messages: candidate.messages,
114
+ });
115
+ }
116
+
117
+ if ("messages" in value && (!Array.isArray(value.messages) || !value.messages.every(isMinimalMessage))) return undefined;
118
+ const messages = Array.isArray(value.messages) ? value.messages : entries.flatMap((entry) => entry.messages);
119
+ return { entries, messages };
120
+ }
121
+
122
+ export function sessionProjectionToMessages(projection: MinimalSessionProjection): MinimalMessage[] {
123
+ return projection.messages ?? projection.entries.flatMap((entry) => entry.messages);
124
+ }
125
+
78
126
  // ============================================================================
79
127
  // Constants
80
128
  // ============================================================================
@@ -114,6 +162,22 @@ const DEFAULT_CACHED_PRICE_RATIO = 0.1;
114
162
  */
115
163
  const DEFAULT_BREAK_EVEN_THRESHOLD = 22;
116
164
 
165
+ /**
166
+ * Default mid_loop break-even threshold (pe-zy4s follow-up). The package's own
167
+ * representative-corpus benchmark (turn-START state definition — the same one
168
+ * the runtime `context` handler uses) favored rejecting mid_loop candidates
169
+ * at cachedPriceRatio r=0.1 (mid_loop-optimal T=1, total realized
170
+ * net benefit ~0.0). This supports a conservative default for the measured
171
+ * corpus, not a universal claim that mid_loop pruning cannot pay off.
172
+ * The reported 2026-09-08 byte-level capture (a mid_loop prune at T=22
173
+ * invalidating 81% of a warm request prefix) illustrates cache invalidation,
174
+ * not an inability to amortize it: enough subsequent calls can recoup a
175
+ * one-time bust. Idle keeps T=22; turn-start classification does not imply
176
+ * the provider cache is cold. Users who want the old behavior can override
177
+ * via gate.breakEvenThresholdByState.mid_loop.
178
+ */
179
+ const DEFAULT_MID_LOOP_BREAK_EVEN_THRESHOLD = 1;
180
+
117
181
  /** Tool names never pruned by default: orchestration/subagent-style tools and todo-like state. */
118
182
  const DEFAULT_PROTECTED_TOOL_NAMES = [
119
183
  "todo",
@@ -222,20 +286,19 @@ export type GateMode = "on" | "off" | "always-apply";
222
286
  * turn-START "idle" population (calls made at the start of a turn) carries
223
287
  * essentially ALL the realized net benefit (idle-optimal T=22, total realized
224
288
  * net benefit ~20,594 token-units), while "mid_loop" carries essentially NONE
225
- * (mid_loop-optimal T=1, total realized net benefit ~0.0 -- i.e. no mid_loop
226
- * candidate is ever worth accepting at r=0.1 under this definition). This is
289
+ * (mid_loop-optimal T=1, total realized net benefit ~0.0 on this corpus). This is
227
290
  * the OPPOSITE of what the pe-c5n9 evidence (measured under the old,
228
291
  * non-runtime-observable turn-END definition) suggested.
229
292
  *
230
293
  * Per the pe-zy4s decision rule (stricter idle default only if idle itself is
231
294
  * shown to be ~worthless): idle is NOT worthless here -- it is the ONLY state
232
- * carrying value at r=0.1 -- so no state-conditioned strictness is justified
233
- * in either direction. The per-state split is therefore kept at PARITY
234
- * (`breakEvenThresholdByState: { idle: DEFAULT_BREAK_EVEN_THRESHOLD, mid_loop:
235
- * DEFAULT_BREAK_EVEN_THRESHOLD }`), both config-overridable. A future ticket
236
- * could consider a stricter mid_loop default given this evidence, but that is
237
- * a new, unreviewed direction outside this ticket's authorized decision rule
238
- * and is left for a follow-up.
295
+ * carrying value at r=0.1 -- so the idle default stays at
296
+ * DEFAULT_BREAK_EVEN_THRESHOLD. The mid_loop default, by the same benchmark,
297
+ * is now DEFAULT_MID_LOOP_BREAK_EVEN_THRESHOLD (=1): the measured candidates
298
+ * did not justify a more permissive threshold at r=0.1. Mid_loop pruning can
299
+ * still amortize over enough subsequent calls; state alone does not establish
300
+ * cache warmth or profitability. Both defaults remain config-overridable via
301
+ * gate.breakEvenThresholdByState.
239
302
  */
240
303
  export type AgentState = "idle" | "mid_loop";
241
304
 
@@ -285,7 +348,7 @@ export function defaultConfig(): DynamicContextPruningConfig {
285
348
  mode: "on",
286
349
  cachedPriceRatio: DEFAULT_CACHED_PRICE_RATIO,
287
350
  breakEvenThreshold: DEFAULT_BREAK_EVEN_THRESHOLD,
288
- breakEvenThresholdByState: { idle: DEFAULT_BREAK_EVEN_THRESHOLD, mid_loop: DEFAULT_BREAK_EVEN_THRESHOLD },
351
+ breakEvenThresholdByState: { idle: DEFAULT_BREAK_EVEN_THRESHOLD, mid_loop: DEFAULT_MID_LOOP_BREAK_EVEN_THRESHOLD },
289
352
  },
290
353
  };
291
354
  }
@@ -684,13 +747,7 @@ export function findToolCallPairIndices(
684
747
  return pair;
685
748
  }
686
749
 
687
- /**
688
- * Fallback correlation for decisions that reference a session entry rather
689
- * than a toolCallId (reserved for future non-tool-call strategies). Zips
690
- * message-producing session entries against the current context projection
691
- * by position; entry/message counts are expected to match in the common
692
- * case, but this degrades gracefully otherwise.
693
- */
750
+ /** Map raw session-entry provenance to projected message positions when Pi exposes it. */
694
751
  function expectedRoleForEntry(entry: MinimalSessionEntry): string | undefined {
695
752
  if (entry.type === "message") return entry.message?.role;
696
753
  if (entry.type === "custom_message") return "custom";
@@ -699,15 +756,53 @@ function expectedRoleForEntry(entry: MinimalSessionEntry): string | undefined {
699
756
  return undefined;
700
757
  }
701
758
 
702
- export function buildEntryIdToMessageIndexMap(
759
+ function buildProjectedEntryIdToMessageIndexMap(
703
760
  entries: MinimalSessionEntry[],
704
761
  messages: MinimalMessage[],
762
+ projection: MinimalSessionProjection,
705
763
  ): Map<string, number> {
706
764
  const map = new Map<string, number>();
765
+ const entryIds = new Set(entries.map((entry) => entry.id));
766
+ let cursor = 0;
767
+
768
+ for (const projectedEntry of projection.entries) {
769
+ let firstMessageIndex: number | undefined;
770
+ for (const projectedMessage of projectedEntry.messages) {
771
+ let messageIndex = messages.indexOf(projectedMessage, cursor);
772
+ if (messageIndex < cursor) messageIndex = -1;
773
+
774
+ if (messageIndex < 0 && typeof projectedMessage.timestamp === "number") {
775
+ messageIndex = messages.findIndex(
776
+ (candidate, index) =>
777
+ index >= cursor && candidate.role === projectedMessage.role && candidate.timestamp === projectedMessage.timestamp,
778
+ );
779
+ }
780
+ if (messageIndex < 0) continue;
781
+ firstMessageIndex ??= messageIndex;
782
+ cursor = messageIndex + 1;
783
+ }
784
+
785
+ if (firstMessageIndex !== undefined && entryIds.has(projectedEntry.sourceEntry.id)) {
786
+ map.set(projectedEntry.sourceEntry.id, firstMessageIndex);
787
+ }
788
+ }
789
+ return map;
790
+ }
791
+
792
+ export function buildEntryIdToMessageIndexMap(
793
+ entries: MinimalSessionEntry[],
794
+ messages: MinimalMessage[],
795
+ projection?: MinimalSessionProjection,
796
+ ): Map<string, number> {
797
+ if (projection) return buildProjectedEntryIdToMessageIndexMap(entries, messages, projection);
798
+
799
+ // Older runtimes expose only raw branch entries; preserve their positional
800
+ // correlation and use role/timestamp only when the counts diverge.
707
801
  const producing = entries.filter((entry) =>
708
802
  entry.type === "message" || entry.type === "custom_message" || entry.type === "branch_summary" || entry.type === "compaction",
709
803
  );
710
804
  const length = Math.min(producing.length, messages.length);
805
+ const map = new Map<string, number>();
711
806
  for (let i = 0; i < length; i++) {
712
807
  const entry = producing[i];
713
808
  const expectedRole = expectedRoleForEntry(entry);
@@ -732,15 +827,21 @@ export function findMessageIndexByRoleAndTimestamp(
732
827
  return index >= 0 ? index : undefined;
733
828
  }
734
829
 
735
- /** Resolve a session entry id to a message index using order-zip, then role+timestamp fallback. */
830
+ /** Resolve a session entry id using projection provenance, then legacy role+timestamp fallback. */
736
831
  export function resolveMessageIndexForEntry(
737
832
  entryId: string,
738
833
  entries: MinimalSessionEntry[],
739
834
  messages: MinimalMessage[],
835
+ projection?: MinimalSessionProjection,
740
836
  ): number | undefined {
741
- const zipMap = buildEntryIdToMessageIndexMap(entries, messages);
837
+ const zipMap = buildEntryIdToMessageIndexMap(entries, messages, projection);
742
838
  const zipped = zipMap.get(entryId);
743
839
  if (zipped !== undefined) return zipped;
840
+
841
+ // An empty projected contribution is an explicit omission/replacement state;
842
+ // only a validated projection may make that context-edit-aware decision.
843
+ if (projection?.entries.some((entry) => entry.sourceEntry.id === entryId && entry.messages.length === 0)) return undefined;
844
+
744
845
  const entry = entries.find((candidate) => candidate.id === entryId);
745
846
  if (!entry) return undefined;
746
847
  return findMessageIndexByRoleAndTimestamp(entry, messages);
@@ -2157,8 +2258,22 @@ export function rebuildDecisionStateFromEntries(entries: MinimalSessionEntry[]):
2157
2258
  // /prune picker helpers (pe-8re9)
2158
2259
  // ============================================================================
2159
2260
 
2160
- /** Convert branch entries into the plain message array the pipeline/pickers correlate against. */
2161
- export function sessionEntriesToMessages(entries: MinimalSessionEntry[]): MinimalMessage[] {
2261
+ function resolveSessionProjection(ctx: ExtensionContext): MinimalSessionProjection | undefined {
2262
+ try {
2263
+ const sessionManager = ctx.sessionManager as unknown as { buildSessionProjection?: () => unknown };
2264
+ const buildProjection = sessionManager.buildSessionProjection;
2265
+ if (typeof buildProjection !== "function") return undefined;
2266
+ return normalizeSessionProjection(buildProjection.call(sessionManager));
2267
+ } catch {
2268
+ return undefined;
2269
+ }
2270
+ }
2271
+
2272
+ export function sessionEntriesToMessages(
2273
+ entries: MinimalSessionEntry[],
2274
+ projection?: MinimalSessionProjection,
2275
+ ): MinimalMessage[] {
2276
+ if (projection) return sessionProjectionToMessages(projection);
2162
2277
  const messages: MinimalMessage[] = [];
2163
2278
  for (const entry of entries) {
2164
2279
  if (entry.type === "message" && entry.message) messages.push(entry.message);
@@ -2273,7 +2388,7 @@ export function formatPrunableItemDetail(item: PrunableItem, cost?: CacheCostMod
2273
2388
 
2274
2389
  /** Plain-text report used both by the non-UI /prune fallback and as a debugging aid. */
2275
2390
  export function formatPrunableItemsReport(items: PrunableItem[]): string[] {
2276
- if (items.length === 0) return ["No prunable tool results found in this session."];
2391
+ if (items.length === 0) return ["No prunable tool results found in the current model context."];
2277
2392
  return items.map((item, index) => `${index + 1}. ${formatPrunableItemOption(item)}`);
2278
2393
  }
2279
2394
 
@@ -2410,7 +2525,7 @@ export function formatStatusReport(input: StatusReportInput): string[] {
2410
2525
  const lines: string[] = [];
2411
2526
  lines.push(`Dynamic context pruning: ${config.enabled ? "ENABLED" : "disabled"}`);
2412
2527
  lines.push(
2413
- `Gate: mode=${config.gate.mode} threshold=${config.gate.breakEvenThreshold} cachedPriceRatio=${config.gate.cachedPriceRatio}`,
2528
+ `Gate: mode=${config.gate.mode} thresholds={idle:${resolveBreakEvenThreshold(config.gate, "idle")}, mid_loop:${resolveBreakEvenThreshold(config.gate, "mid_loop")}} cachedPriceRatio=${config.gate.cachedPriceRatio}`,
2414
2529
  );
2415
2530
  lines.push("Strategies:");
2416
2531
  lines.push(` dedupe: ${config.strategies.dedupe.enabled ? "on" : "off"}`);
@@ -2581,7 +2696,8 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
2581
2696
  description: "Review, manually prune, and restore prunable tool results (interactive picker in TUI/RPC)",
2582
2697
  handler: async (_args, ctx) => {
2583
2698
  const branchEntries = ctx.sessionManager.getBranch() as unknown as MinimalSessionEntry[];
2584
- const messages = sessionEntriesToMessages(branchEntries);
2699
+ const projection = resolveSessionProjection(ctx);
2700
+ const messages = sessionEntriesToMessages(branchEntries, projection);
2585
2701
  const activeByToolCallId = buildActiveResultDecisionMap(persistedDecisions);
2586
2702
  const restoredToolCallIds = new Set(
2587
2703
  Array.from(lastDecisionByKey.values())
@@ -2591,19 +2707,20 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
2591
2707
  const items = buildPrunableItems(messages, activeByToolCallId, restoredToolCallIds);
2592
2708
 
2593
2709
  if (!ctx.hasUI) {
2594
- notify(ctx, ["/prune: no interactive UI available. Prunable tool results in this session:", "", ...formatPrunableItemsReport(items)].join("\n"), "info");
2710
+ notify(ctx, ["/prune: no interactive UI available. Prunable tool results in the current model context:", "", ...formatPrunableItemsReport(items)].join("\n"), "info");
2595
2711
  return;
2596
2712
  }
2597
2713
 
2598
2714
  if (items.length === 0) {
2599
- notify(ctx, "No prunable tool results found in this session.", "info");
2715
+ notify(ctx, "No prunable tool results found in the current model context.", "info");
2600
2716
  return;
2601
2717
  }
2602
2718
 
2603
2719
  const doneLabel = "Done";
2604
2720
  while (true) {
2605
2721
  const latestBranch = ctx.sessionManager.getBranch() as unknown as MinimalSessionEntry[];
2606
- const latestMessages = sessionEntriesToMessages(latestBranch);
2722
+ const latestProjection = resolveSessionProjection(ctx);
2723
+ const latestMessages = sessionEntriesToMessages(latestBranch, latestProjection);
2607
2724
  const latestActive = buildActiveResultDecisionMap(persistedDecisions);
2608
2725
  const latestRestoredToolCallIds = new Set(
2609
2726
  Array.from(lastDecisionByKey.values())
@@ -2612,7 +2729,7 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
2612
2729
  );
2613
2730
  const latestItems = buildPrunableItems(latestMessages, latestActive, latestRestoredToolCallIds);
2614
2731
  if (latestItems.length === 0) {
2615
- notify(ctx, "No prunable tool results found in this session.", "info");
2732
+ notify(ctx, "No prunable tool results found in the current model context.", "info");
2616
2733
  return;
2617
2734
  }
2618
2735
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-dynamic-context-pruning",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "type": "module",
5
5
  "description": "A pi extension that dynamically prunes stale context to keep sessions lean.",
6
6
  "keywords": [