pi-dynamic-context-pruning 0.1.9 → 0.1.11

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 +18 -6
  2. package/index.ts +134 -19
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -27,11 +27,23 @@ and why it hasn't been built yet.
27
27
  key wins when replaying history, so a decision can be pruned, restored, and
28
28
  re-pruned any number of times.
29
29
  - **Recomputed every call, not on a timer.** All three automatic strategies run
30
- fresh on every `context` event, over the current message array. Nothing is
31
- pruned "once and forgotten"; if a tool result would no longer qualify (e.g.
32
- it's now within the protected recency window), it isn't proposed again, but
33
- an already-applied, persisted decision still applies until explicitly
34
- restored.
30
+ fresh on every `context` event, over the current message array. Pi 0.99's
31
+ `context` hook intentionally receives the mutable conversation without system
32
+ messages; Pi restores its system prompt and tool state after the handler. The
33
+ extension does not try to rebuild that request-only envelope.
34
+ - **Canonical picker input.** `/prune` uses Pi's canonical session projection when
35
+ available, so context omissions and replacements, branch selection, and tool
36
+ pairing match the provider-visible conversation. Older hosts retain the raw
37
+ message-entry fallback.
38
+ - **Nested calls stay metadata.** Pi records bounded `nestedCalls` metadata on a
39
+ parent tool result, but nested results are not transcript messages. Strategies
40
+ count and prune only the parent transcript tool result; they never materialize
41
+ child entries, double-count child output, or infer complete history from a
42
+ truncated/incomplete record.
43
+ - **Persisted decisions remain branch-local.** Nothing is pruned "once and
44
+ forgotten"; if a tool result would no longer qualify (e.g. it's now within the
45
+ protected recency window), it isn't proposed again, but an already-applied,
46
+ persisted decision still applies until explicitly restored.
35
47
 
36
48
  ## Strategies
37
49
 
@@ -154,7 +166,7 @@ Gate modes (`/context-pruning gate <mode>`):
154
166
  ### `/prune`
155
167
 
156
168
  Interactive picker (TUI/RPC) over every prunable tool result in the current
157
- branch:
169
+ model context:
158
170
 
159
171
  ```text
160
172
  /prune
package/index.ts CHANGED
@@ -51,6 +51,8 @@ export interface MinimalToolResultMessage {
51
51
  toolCallId: string;
52
52
  toolName: string;
53
53
  content: (MinimalTextContent | MinimalImageContent)[];
54
+ /** Bounded nested-call metadata; child calls have no transcript results to prune. */
55
+ nestedCalls?: unknown;
54
56
  isError: boolean;
55
57
  timestamp?: number;
56
58
  [key: string]: unknown;
@@ -75,6 +77,57 @@ export interface MinimalSessionEntry {
75
77
  [key: string]: unknown;
76
78
  }
77
79
 
80
+ export interface MinimalProjectedSessionEntry {
81
+ sourceEntry: MinimalSessionEntry;
82
+ messages: MinimalMessage[];
83
+ }
84
+
85
+ export interface MinimalSessionProjection {
86
+ entries: MinimalProjectedSessionEntry[];
87
+ messages?: MinimalMessage[];
88
+ }
89
+
90
+ function isRecord(value: unknown): value is Record<string, unknown> {
91
+ return typeof value === "object" && value !== null;
92
+ }
93
+
94
+ function isMinimalMessage(value: unknown): value is MinimalMessage {
95
+ return isRecord(value) && typeof value.role === "string" && value.role.length > 0;
96
+ }
97
+
98
+ function isProjectionSourceEntry(value: unknown): value is MinimalSessionEntry {
99
+ return isRecord(value)
100
+ && typeof value.type === "string"
101
+ && value.type.length > 0
102
+ && typeof value.id === "string"
103
+ && value.id.length > 0;
104
+ }
105
+
106
+ export function normalizeSessionProjection(value: unknown): MinimalSessionProjection | undefined {
107
+ if (!isRecord(value) || !Array.isArray(value.entries)) return undefined;
108
+
109
+ const entries: MinimalProjectedSessionEntry[] = [];
110
+ for (const candidate of value.entries) {
111
+ if (!isRecord(candidate) || !isProjectionSourceEntry(candidate.sourceEntry) || !Array.isArray(candidate.messages)) return undefined;
112
+ if (!candidate.messages.every(isMinimalMessage)) return undefined;
113
+ entries.push({
114
+ sourceEntry: candidate.sourceEntry,
115
+ messages: candidate.messages,
116
+ });
117
+ }
118
+
119
+ // Entries carry the provenance that Pi uses to apply omissions and
120
+ // replacements. Validate the optional flattened field for compatibility, but
121
+ // derive the messages used by pruning from entries so stale/invented records
122
+ // cannot bypass canonical context edits.
123
+ if ("messages" in value && (!Array.isArray(value.messages) || !value.messages.every(isMinimalMessage))) return undefined;
124
+ return { entries, messages: entries.flatMap((entry) => entry.messages) };
125
+ }
126
+
127
+ export function sessionProjectionToMessages(projection: MinimalSessionProjection): MinimalMessage[] {
128
+ return projection.entries.flatMap((entry) => entry.messages);
129
+ }
130
+
78
131
  // ============================================================================
79
132
  // Constants
80
133
  // ============================================================================
@@ -699,13 +752,7 @@ export function findToolCallPairIndices(
699
752
  return pair;
700
753
  }
701
754
 
702
- /**
703
- * Fallback correlation for decisions that reference a session entry rather
704
- * than a toolCallId (reserved for future non-tool-call strategies). Zips
705
- * message-producing session entries against the current context projection
706
- * by position; entry/message counts are expected to match in the common
707
- * case, but this degrades gracefully otherwise.
708
- */
755
+ /** Map raw session-entry provenance to projected message positions when Pi exposes it. */
709
756
  function expectedRoleForEntry(entry: MinimalSessionEntry): string | undefined {
710
757
  if (entry.type === "message") return entry.message?.role;
711
758
  if (entry.type === "custom_message") return "custom";
@@ -714,15 +761,53 @@ function expectedRoleForEntry(entry: MinimalSessionEntry): string | undefined {
714
761
  return undefined;
715
762
  }
716
763
 
717
- export function buildEntryIdToMessageIndexMap(
764
+ function buildProjectedEntryIdToMessageIndexMap(
718
765
  entries: MinimalSessionEntry[],
719
766
  messages: MinimalMessage[],
767
+ projection: MinimalSessionProjection,
720
768
  ): Map<string, number> {
721
769
  const map = new Map<string, number>();
770
+ const entryIds = new Set(entries.map((entry) => entry.id));
771
+ let cursor = 0;
772
+
773
+ for (const projectedEntry of projection.entries) {
774
+ let firstMessageIndex: number | undefined;
775
+ for (const projectedMessage of projectedEntry.messages) {
776
+ let messageIndex = messages.indexOf(projectedMessage, cursor);
777
+ if (messageIndex < cursor) messageIndex = -1;
778
+
779
+ if (messageIndex < 0 && typeof projectedMessage.timestamp === "number") {
780
+ messageIndex = messages.findIndex(
781
+ (candidate, index) =>
782
+ index >= cursor && candidate.role === projectedMessage.role && candidate.timestamp === projectedMessage.timestamp,
783
+ );
784
+ }
785
+ if (messageIndex < 0) continue;
786
+ firstMessageIndex ??= messageIndex;
787
+ cursor = messageIndex + 1;
788
+ }
789
+
790
+ if (firstMessageIndex !== undefined && entryIds.has(projectedEntry.sourceEntry.id)) {
791
+ map.set(projectedEntry.sourceEntry.id, firstMessageIndex);
792
+ }
793
+ }
794
+ return map;
795
+ }
796
+
797
+ export function buildEntryIdToMessageIndexMap(
798
+ entries: MinimalSessionEntry[],
799
+ messages: MinimalMessage[],
800
+ projection?: MinimalSessionProjection,
801
+ ): Map<string, number> {
802
+ if (projection) return buildProjectedEntryIdToMessageIndexMap(entries, messages, projection);
803
+
804
+ // Older runtimes expose only raw branch entries; preserve their positional
805
+ // correlation and use role/timestamp only when the counts diverge.
722
806
  const producing = entries.filter((entry) =>
723
807
  entry.type === "message" || entry.type === "custom_message" || entry.type === "branch_summary" || entry.type === "compaction",
724
808
  );
725
809
  const length = Math.min(producing.length, messages.length);
810
+ const map = new Map<string, number>();
726
811
  for (let i = 0; i < length; i++) {
727
812
  const entry = producing[i];
728
813
  const expectedRole = expectedRoleForEntry(entry);
@@ -747,15 +832,21 @@ export function findMessageIndexByRoleAndTimestamp(
747
832
  return index >= 0 ? index : undefined;
748
833
  }
749
834
 
750
- /** Resolve a session entry id to a message index using order-zip, then role+timestamp fallback. */
835
+ /** Resolve a session entry id using projection provenance, then legacy role+timestamp fallback. */
751
836
  export function resolveMessageIndexForEntry(
752
837
  entryId: string,
753
838
  entries: MinimalSessionEntry[],
754
839
  messages: MinimalMessage[],
840
+ projection?: MinimalSessionProjection,
755
841
  ): number | undefined {
756
- const zipMap = buildEntryIdToMessageIndexMap(entries, messages);
842
+ const zipMap = buildEntryIdToMessageIndexMap(entries, messages, projection);
757
843
  const zipped = zipMap.get(entryId);
758
844
  if (zipped !== undefined) return zipped;
845
+
846
+ // An empty projected contribution is an explicit omission/replacement state;
847
+ // only a validated projection may make that context-edit-aware decision.
848
+ if (projection?.entries.some((entry) => entry.sourceEntry.id === entryId && entry.messages.length === 0)) return undefined;
849
+
759
850
  const entry = entries.find((candidate) => candidate.id === entryId);
760
851
  if (!entry) return undefined;
761
852
  return findMessageIndexByRoleAndTimestamp(entry, messages);
@@ -1512,7 +1603,13 @@ export interface ToolCallOccurrence {
1512
1603
  isError: boolean;
1513
1604
  }
1514
1605
 
1515
- /** Collect every assistant toolCall block that has a matching toolResult message, in message order. */
1606
+ /**
1607
+ * Collect every transcript assistant toolCall block that has a matching
1608
+ * transcript toolResult message, in message order. `nestedCalls` is deliberately
1609
+ * not expanded: Pi keeps only bounded call metadata there and does not record
1610
+ * child results as transcript messages, so expanding it would double-count or
1611
+ * invent prune targets.
1612
+ */
1516
1613
  export function collectCompletedToolCallOccurrences(messages: MinimalMessage[]): ToolCallOccurrence[] {
1517
1614
  const resultIndexById = new Map<string, number>();
1518
1615
  const isErrorById = new Map<string, boolean>();
@@ -2172,8 +2269,22 @@ export function rebuildDecisionStateFromEntries(entries: MinimalSessionEntry[]):
2172
2269
  // /prune picker helpers (pe-8re9)
2173
2270
  // ============================================================================
2174
2271
 
2175
- /** Convert branch entries into the plain message array the pipeline/pickers correlate against. */
2176
- export function sessionEntriesToMessages(entries: MinimalSessionEntry[]): MinimalMessage[] {
2272
+ function resolveSessionProjection(ctx: ExtensionContext): MinimalSessionProjection | undefined {
2273
+ try {
2274
+ const sessionManager = ctx.sessionManager as unknown as { buildSessionProjection?: () => unknown };
2275
+ const buildProjection = sessionManager.buildSessionProjection;
2276
+ if (typeof buildProjection !== "function") return undefined;
2277
+ return normalizeSessionProjection(buildProjection.call(sessionManager));
2278
+ } catch {
2279
+ return undefined;
2280
+ }
2281
+ }
2282
+
2283
+ export function sessionEntriesToMessages(
2284
+ entries: MinimalSessionEntry[],
2285
+ projection?: MinimalSessionProjection,
2286
+ ): MinimalMessage[] {
2287
+ if (projection) return sessionProjectionToMessages(projection);
2177
2288
  const messages: MinimalMessage[] = [];
2178
2289
  for (const entry of entries) {
2179
2290
  if (entry.type === "message" && entry.message) messages.push(entry.message);
@@ -2218,6 +2329,8 @@ export function buildPrunableItems(
2218
2329
  const items: PrunableItem[] = [];
2219
2330
  for (const occurrence of collectCompletedToolCallOccurrences(messages)) {
2220
2331
  const resultMessage = messages[occurrence.resultIndex] as MinimalToolResultMessage;
2332
+ // Only provider-visible transcript content is economically attributable;
2333
+ // bounded nested-call metadata has no child result content to estimate.
2221
2334
  const estimatedTokens = estimateTokensForContent(resultMessage.content);
2222
2335
  const activeDecision = activeByToolCallId.get(occurrence.toolCallId);
2223
2336
  const status: PrunableItemStatus = activeDecision
@@ -2288,7 +2401,7 @@ export function formatPrunableItemDetail(item: PrunableItem, cost?: CacheCostMod
2288
2401
 
2289
2402
  /** Plain-text report used both by the non-UI /prune fallback and as a debugging aid. */
2290
2403
  export function formatPrunableItemsReport(items: PrunableItem[]): string[] {
2291
- if (items.length === 0) return ["No prunable tool results found in this session."];
2404
+ if (items.length === 0) return ["No prunable tool results found in the current model context."];
2292
2405
  return items.map((item, index) => `${index + 1}. ${formatPrunableItemOption(item)}`);
2293
2406
  }
2294
2407
 
@@ -2596,7 +2709,8 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
2596
2709
  description: "Review, manually prune, and restore prunable tool results (interactive picker in TUI/RPC)",
2597
2710
  handler: async (_args, ctx) => {
2598
2711
  const branchEntries = ctx.sessionManager.getBranch() as unknown as MinimalSessionEntry[];
2599
- const messages = sessionEntriesToMessages(branchEntries);
2712
+ const projection = resolveSessionProjection(ctx);
2713
+ const messages = sessionEntriesToMessages(branchEntries, projection);
2600
2714
  const activeByToolCallId = buildActiveResultDecisionMap(persistedDecisions);
2601
2715
  const restoredToolCallIds = new Set(
2602
2716
  Array.from(lastDecisionByKey.values())
@@ -2606,19 +2720,20 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
2606
2720
  const items = buildPrunableItems(messages, activeByToolCallId, restoredToolCallIds);
2607
2721
 
2608
2722
  if (!ctx.hasUI) {
2609
- notify(ctx, ["/prune: no interactive UI available. Prunable tool results in this session:", "", ...formatPrunableItemsReport(items)].join("\n"), "info");
2723
+ notify(ctx, ["/prune: no interactive UI available. Prunable tool results in the current model context:", "", ...formatPrunableItemsReport(items)].join("\n"), "info");
2610
2724
  return;
2611
2725
  }
2612
2726
 
2613
2727
  if (items.length === 0) {
2614
- notify(ctx, "No prunable tool results found in this session.", "info");
2728
+ notify(ctx, "No prunable tool results found in the current model context.", "info");
2615
2729
  return;
2616
2730
  }
2617
2731
 
2618
2732
  const doneLabel = "Done";
2619
2733
  while (true) {
2620
2734
  const latestBranch = ctx.sessionManager.getBranch() as unknown as MinimalSessionEntry[];
2621
- const latestMessages = sessionEntriesToMessages(latestBranch);
2735
+ const latestProjection = resolveSessionProjection(ctx);
2736
+ const latestMessages = sessionEntriesToMessages(latestBranch, latestProjection);
2622
2737
  const latestActive = buildActiveResultDecisionMap(persistedDecisions);
2623
2738
  const latestRestoredToolCallIds = new Set(
2624
2739
  Array.from(lastDecisionByKey.values())
@@ -2627,7 +2742,7 @@ export default function dynamicContextPruningExtension(pi: ExtensionAPI) {
2627
2742
  );
2628
2743
  const latestItems = buildPrunableItems(latestMessages, latestActive, latestRestoredToolCallIds);
2629
2744
  if (latestItems.length === 0) {
2630
- notify(ctx, "No prunable tool results found in this session.", "info");
2745
+ notify(ctx, "No prunable tool results found in the current model context.", "info");
2631
2746
  return;
2632
2747
  }
2633
2748
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-dynamic-context-pruning",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "type": "module",
5
5
  "description": "A pi extension that dynamically prunes stale context to keep sessions lean.",
6
6
  "keywords": [