@howaboua/pi-notes-compaction 0.0.4 → 0.0.6

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/src/windows.ts CHANGED
@@ -9,20 +9,24 @@ import type {
9
9
  } from "@earendil-works/pi-coding-agent";
10
10
  import { keyHint } from "@earendil-works/pi-coding-agent";
11
11
  import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
12
- import type { WindowIdentity } from "./bridge.js";
12
+ import type { NotesBridge, WindowIdentity } from "./bridge.js";
13
+ import {
14
+ renderTaskBoundaryReminder,
15
+ taskBoundaryEligible,
16
+ } from "./task-boundary.js";
13
17
 
14
18
  export const WINDOW_MESSAGE = "notes-compaction:window:v1";
15
19
  export const SETTLEMENT_ENTRY = "notes-compaction:settled:v1";
16
20
  export interface WindowDetails {
17
21
  protocol: 1;
18
- kind: "window" | "identity" | "reminder" | "urgent";
22
+ kind: "window" | "identity" | "reminder" | "urgent" | "task-boundary";
19
23
  identity: WindowIdentity;
20
24
  trim: boolean;
21
25
  }
22
26
  const GUIDANCE = `<context_window_guidance>
23
- Keep one checkpoint per task at a stable path: request, constraints, decisions, progress, next steps, history IDs. Replace stale state; mark completion in place. Keep reusable findings and deferred ideas in separate topic notes; link, don't copy. Recording isn't permission to implement.
27
+ Notes persist across windows. Keep one checkpoint per task at a stable path, covering the request, constraints, decisions, progress, next steps and history IDs so you can resume without rereading the conversation. Replace stale state; mark completion in place. Keep reusable findings and deferred ideas in separate topic notes; link, don't copy. Recording isn't permission to implement.
24
28
 
25
- Save changed state after substantial work, before replying, and before new_context or handoff. Skip routine or unchanged state. Include checkpoint paths in handoffs. After rollover, read the checkpoint, then linked notes as needed; history only for missing details.
29
+ Save changed state after substantial work, before replying, and before new_context or handoff. Skip routine or unchanged state. Include checkpoint paths in handoffs. After rollover, read the checkpoint, then linked notes as needed. History retrieves earlier conversation; use it only for missing details.
26
30
  </context_window_guidance>`;
27
31
 
28
32
  export function registerWindowRenderer(pi: ExtensionAPI): void {
@@ -32,11 +36,13 @@ export function registerWindowRenderer(pi: ExtensionAPI): void {
32
36
  const details = parseWindowDetails(message.details);
33
37
  if (!details || typeof message.content !== "string") return undefined;
34
38
  const title =
35
- details.kind === "urgent"
36
- ? "Context nearly full · Save notes and start a new window now"
37
- : details.kind === "reminder"
38
- ? "Context checkpoint reminder · Save notes and start a new window"
39
- : `Context window ${details.identity.windowNumber + 1} · Notes and history`;
39
+ details.kind === "task-boundary"
40
+ ? "Task-boundary reminder"
41
+ : details.kind === "urgent"
42
+ ? "Context nearly full · Save notes and start a new window now"
43
+ : details.kind === "reminder"
44
+ ? "Context checkpoint reminder · Save notes and start a new window"
45
+ : `Context window ${details.identity.windowNumber + 1} · Notes and history`;
40
46
  const box = new Box(outputPad, 1, (text) =>
41
47
  theme.bg("customMessageBg", text),
42
48
  );
@@ -85,7 +91,7 @@ function parseWindowDetails(value: unknown): WindowDetails | undefined {
85
91
  if (
86
92
  details.protocol !== 1 ||
87
93
  !ids ||
88
- !["window", "identity", "reminder", "urgent"].includes(
94
+ !["window", "identity", "reminder", "urgent", "task-boundary"].includes(
89
95
  details.kind ?? "",
90
96
  ) ||
91
97
  typeof details.trim !== "boolean"
@@ -100,7 +106,9 @@ function parseWindowDetails(value: unknown): WindowDetails | undefined {
100
106
  }
101
107
 
102
108
  /** Understand previous PCC window IDs for familiar history lookup, without importing its runtime. */
103
- export function windowDetails(entry: SessionEntry): WindowDetails | undefined {
109
+ export function windowDetails(
110
+ entry: SessionEntry | CustomMessageEntryDraft,
111
+ ): WindowDetails | undefined {
104
112
  if (entry.type !== "custom_message") return;
105
113
  return messageWindowDetails(entry.customType, entry.details);
106
114
  }
@@ -122,14 +130,14 @@ function messageWindowDetails(
122
130
  !details ||
123
131
  typeof details !== "object" ||
124
132
  !("kind" in details) ||
125
- details.kind !== "window"
133
+ (details.kind !== "window" && details.kind !== "task-boundary")
126
134
  )
127
135
  return;
128
136
  const ids = identity(details);
129
137
  return ids
130
138
  ? {
131
139
  protocol: 1,
132
- kind: "window",
140
+ kind: details.kind,
133
141
  identity: ids,
134
142
  trim:
135
143
  "trimPreviousWindow" in details &&
@@ -169,26 +177,48 @@ export function windowMessage(
169
177
 
170
178
  export class Windows {
171
179
  current: WindowIdentity | undefined;
180
+ private identityEntry:
181
+ | Extract<SessionEntry, { type: "custom_message" }>
182
+ | undefined;
183
+ private restoredIdentity:
184
+ | {
185
+ entryId: string;
186
+ timestamp: number;
187
+ prepare: NotesBridge["prepareReminder"];
188
+ message: AgentMessage;
189
+ }
190
+ | undefined;
172
191
  private compactedSinceBoundary = false;
173
192
  private reminders = new Set<string>();
174
193
  restore(entries: readonly SessionEntry[]): void {
175
194
  this.current = undefined;
195
+ this.identityEntry = undefined;
176
196
  this.compactedSinceBoundary = false;
177
197
  this.reminders.clear();
178
198
  for (const entry of entries) {
179
199
  const details = windowDetails(entry);
200
+ if (
201
+ entry.type === "custom_message" &&
202
+ (details?.kind === "window" || details?.kind === "identity")
203
+ )
204
+ this.identityEntry = entry;
180
205
  if (details?.kind === "window") {
181
206
  this.current = details.identity;
182
- this.compactedSinceBoundary = false;
207
+ if (details.trim) this.compactedSinceBoundary = false;
183
208
  } else if (
184
209
  details &&
185
- (details.kind === "reminder" || details.kind === "urgent")
210
+ (details.kind === "reminder" ||
211
+ details.kind === "urgent" ||
212
+ details.kind === "task-boundary")
186
213
  )
187
214
  this.reminders.add(
188
215
  `${details.identity.currentWindowId}:${details.kind}`,
189
216
  );
190
217
  if (entry.type === "compaction") {
191
- this.reminders.clear();
218
+ // Compaction frees capacity, but does not create a new window identity.
219
+ this.reminders = new Set(
220
+ [...this.reminders].filter((key) => key.endsWith(":task-boundary")),
221
+ );
192
222
  this.compactedSinceBoundary = true;
193
223
  }
194
224
  }
@@ -226,21 +256,47 @@ export class Windows {
226
256
  : Math.round((remainingTokens / contextWindow) * 1000) / 10,
227
257
  };
228
258
  }
229
- reminder(ctx: ExtensionContext): CustomMessageEntryDraft | undefined {
259
+ reminder(
260
+ ctx: ExtensionContext,
261
+ taskBoundaryReminder = 0,
262
+ checkpointReminder = true,
263
+ ): CustomMessageEntryDraft | undefined {
230
264
  const { remainingTokens, contextWindow, remainingPercent } =
231
265
  this.remaining(ctx);
232
- if (!this.current || remainingTokens === undefined) return;
233
- const used = 100 * (1 - remainingTokens / contextWindow);
234
- const kind = used >= 90 ? "urgent" : used >= 85 ? "reminder" : undefined;
235
- if (!kind || this.reminders.has(`${this.current.currentWindowId}:${kind}`))
266
+ if (
267
+ !this.current ||
268
+ remainingTokens === undefined ||
269
+ remainingPercent === undefined
270
+ )
236
271
  return;
237
- this.reminders.add(`${this.current.currentWindowId}:reminder`);
272
+ const used = 100 * (1 - remainingTokens / contextWindow);
273
+ let kind: WindowDetails["kind"] | undefined = checkpointReminder
274
+ ? used >= 90
275
+ ? "urgent"
276
+ : used >= 85
277
+ ? "reminder"
278
+ : undefined
279
+ : undefined;
280
+ if (kind && this.reminders.has(`${this.current.currentWindowId}:${kind}`))
281
+ kind = undefined;
282
+ if (
283
+ !kind &&
284
+ taskBoundaryReminder &&
285
+ !this.reminders.has(`${this.current.currentWindowId}:task-boundary`) &&
286
+ taskBoundaryEligible(ctx, taskBoundaryReminder)
287
+ )
288
+ kind = "task-boundary";
289
+ if (!kind) return;
290
+ this.reminders.add(`${this.current.currentWindowId}:${kind}`);
238
291
  if (kind === "urgent")
239
- this.reminders.add(`${this.current.currentWindowId}:urgent`);
292
+ this.reminders.add(`${this.current.currentWindowId}:reminder`);
240
293
  return {
241
294
  type: "custom_message",
242
295
  customType: WINDOW_MESSAGE,
243
- content: `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% remaining. Checkpoint the active request, state and known history IDs in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
296
+ content:
297
+ kind === "task-boundary"
298
+ ? renderTaskBoundaryReminder(remainingPercent)
299
+ : `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context remaining. Save the task state in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
244
300
  display: true,
245
301
  details: {
246
302
  protocol: 1,
@@ -250,8 +306,74 @@ export class Windows {
250
306
  } satisfies WindowDetails,
251
307
  };
252
308
  }
253
- projectMessages(messages: readonly AgentMessage[]): AgentMessage[] {
254
- if (this.compactedSinceBoundary) return [...messages];
309
+ projectMessages(
310
+ messages: readonly AgentMessage[],
311
+ prepareIdentity?: NotesBridge["prepareReminder"],
312
+ ): AgentMessage[] {
313
+ if (this.compactedSinceBoundary) {
314
+ const summary = messages.findIndex(
315
+ (message) => message.role === "compactionSummary",
316
+ );
317
+ const entry = this.identityEntry;
318
+ const details = entry && windowDetails(entry);
319
+ const hasIdentity = messages.some((message) => {
320
+ const current =
321
+ message.role === "custom" &&
322
+ messageWindowDetails(message.customType, message.details);
323
+ return (
324
+ current &&
325
+ (current.kind === "window" || current.kind === "identity") &&
326
+ current.identity.currentWindowId === this.current?.currentWindowId
327
+ );
328
+ });
329
+ if (
330
+ summary < 0 ||
331
+ messages[0]?.role !== "system" ||
332
+ !entry ||
333
+ !details ||
334
+ typeof entry.content !== "string" ||
335
+ hasIdentity
336
+ )
337
+ return [...messages];
338
+ const timestamp = messages[summary]!.timestamp;
339
+ if (
340
+ this.restoredIdentity?.entryId !== entry.id ||
341
+ this.restoredIdentity.timestamp !== timestamp ||
342
+ this.restoredIdentity.prepare !== prepareIdentity
343
+ ) {
344
+ const draft: CustomMessageEntryDraft = {
345
+ type: "custom_message",
346
+ customType: WINDOW_MESSAGE,
347
+ content: `${entry.content}\n\nIf no checkpoint is available, use history to recover missing context.`,
348
+ display: false,
349
+ details: {
350
+ ...details,
351
+ kind: "identity",
352
+ trim: false,
353
+ } satisfies WindowDetails,
354
+ };
355
+ const prepared = prepareIdentity?.(draft) ?? draft;
356
+ this.restoredIdentity = {
357
+ entryId: entry.id,
358
+ timestamp,
359
+ prepare: prepareIdentity,
360
+ message: {
361
+ role: "custom",
362
+ customType: prepared.customType,
363
+ content: prepared.content,
364
+ display: prepared.display,
365
+ details: prepared.details,
366
+ timestamp,
367
+ },
368
+ };
369
+ }
370
+ // Carry the older identity ahead of its summary, outside opaque native replay.
371
+ return [
372
+ ...messages.slice(0, summary),
373
+ this.restoredIdentity.message,
374
+ ...messages.slice(summary),
375
+ ];
376
+ }
255
377
  let boundary = -1;
256
378
  for (let i = 0; i < messages.length; i++) {
257
379
  const message = messages[i]!;
@@ -261,7 +383,7 @@ export class Windows {
261
383
  throw new Error(
262
384
  "Invalid saved context window. Open an intact session branch to continue.",
263
385
  );
264
- if (details?.kind === "window") boundary = details.trim ? i : -1;
386
+ if (details?.kind === "window" && details.trim) boundary = i;
265
387
  }
266
388
  if (boundary < 0) return [...messages];
267
389
  const system = getCurrentSystemMessage(messages.slice(0, boundary));
@@ -273,7 +395,7 @@ export class Windows {
273
395
  let boundary = -1;
274
396
  for (let i = 0; i < entries.length; i++) {
275
397
  const details = windowDetails(entries[i]!);
276
- if (details?.kind === "window") boundary = details.trim ? i : -1;
398
+ if (details?.kind === "window" && details.trim) boundary = i;
277
399
  // Normal Pi/PCC compaction has already chosen its own checkpoint.
278
400
  if (entries[i]!.type === "compaction") boundary = -1;
279
401
  }