@howaboua/pi-notes-compaction 0.0.8 → 0.0.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 (53) hide show
  1. package/CHANGELOG.md +31 -5
  2. package/PCC-INTEGRATION.md +7 -98
  3. package/README.md +22 -14
  4. package/package.json +7 -3
  5. package/src/activation.ts +152 -0
  6. package/src/agent-identity.ts +119 -0
  7. package/src/attachment-snapshot.ts +103 -0
  8. package/src/binding-startup.ts +30 -0
  9. package/src/bridge.ts +1 -43
  10. package/src/compaction-projection.ts +88 -0
  11. package/src/context-owner.ts +103 -0
  12. package/src/context-sharing.ts +144 -0
  13. package/src/extension-hooks.ts +198 -0
  14. package/src/extension-sharing.ts +118 -0
  15. package/src/fresh-checkpoint.ts +117 -0
  16. package/src/fresh-notes.ts +141 -26
  17. package/src/history-search-protocol.ts +39 -0
  18. package/src/history-search-pruning.mjs +120 -0
  19. package/src/history-search-worker.mjs +256 -0
  20. package/src/history-search.ts +269 -0
  21. package/src/history.ts +219 -48
  22. package/src/idle-admission.ts +201 -0
  23. package/src/index.ts +71 -401
  24. package/src/integrations.ts +159 -0
  25. package/src/lifecycle.ts +63 -448
  26. package/src/note-save-marker.ts +112 -0
  27. package/src/notes-lookup.ts +112 -0
  28. package/src/notes.ts +25 -30
  29. package/src/query-executor.ts +190 -0
  30. package/src/remote.ts +357 -0
  31. package/src/rollover.ts +212 -0
  32. package/src/saved-session.ts +44 -7
  33. package/src/session-pruning-content.ts +237 -0
  34. package/src/session-pruning-plan.ts +243 -0
  35. package/src/session-pruning-policy.ts +20 -0
  36. package/src/session-pruning-screen.ts +130 -0
  37. package/src/session-pruning-source.ts +44 -0
  38. package/src/session-pruning-transaction.ts +141 -0
  39. package/src/session-pruning.ts +142 -0
  40. package/src/settings-command.ts +77 -0
  41. package/src/settings-screen.ts +89 -20
  42. package/src/settings.ts +152 -15
  43. package/src/shared-notes.ts +37 -14
  44. package/src/sharing-service.ts +348 -0
  45. package/src/store.ts +31 -0
  46. package/src/task-boundary.ts +6 -1
  47. package/src/tool-contracts.ts +279 -0
  48. package/src/tools.ts +19 -556
  49. package/src/tree-archive.ts +149 -0
  50. package/src/tree-checkpoint.ts +170 -0
  51. package/src/tree-handoff-read.ts +192 -0
  52. package/src/window-checkpoint.ts +105 -0
  53. package/src/windows.ts +28 -8
package/src/history.ts CHANGED
@@ -1,4 +1,6 @@
1
1
  import type { SessionEntry } from "@earendil-works/pi-coding-agent";
2
+ import type { HistorySearch } from "./history-search.js";
3
+ import { buildTreeArchiveIndex } from "./tree-archive.js";
2
4
  import { windowDetails } from "./windows.js";
3
5
 
4
6
  interface HistoryItem {
@@ -10,6 +12,23 @@ interface HistoryItem {
10
12
  content: string;
11
13
  }
12
14
 
15
+ // Pi entries are immutable once persisted. Rendering is lazy so indexing never
16
+ // serializes the ongoing context, and repeated lookups reuse unchanged text.
17
+ const rendered = new WeakMap<SessionEntry, string>();
18
+ const cachedItems = new WeakMap<SessionEntry, HistoryItem>();
19
+ const indexItems = new WeakMap<
20
+ HistoryItem,
21
+ Pick<HistoryItem, "item_id" | "content">
22
+ >();
23
+ function content(entry: SessionEntry, render: () => string): string {
24
+ let value = rendered.get(entry);
25
+ if (value === undefined) {
26
+ value = render();
27
+ rendered.set(entry, value);
28
+ }
29
+ return value;
30
+ }
31
+
13
32
  function customHistoryRole(
14
33
  entry: Extract<SessionEntry, { type: "custom_message" }>,
15
34
  ): string {
@@ -41,22 +60,68 @@ function customHistoryRole(
41
60
  : "user";
42
61
  }
43
62
 
44
- /** Pi's selected JSONL branch is the archive. No transcript database or Tree backend. */
45
- export function useHistory(
63
+ /** Pi's selected JSONL branch is the archive. */
64
+ async function historyWindows(
46
65
  entries: readonly SessionEntry[],
47
- params: Record<string, unknown>,
48
66
  sessionId: string,
49
- ): Record<string, unknown> {
67
+ allEntries: readonly SessionEntry[],
68
+ signal?: AbortSignal,
69
+ ): Promise<{ windows: Map<string, HistoryItem[]>; retired: Set<string> }> {
70
+ const archive = buildTreeArchiveIndex(allEntries, entries);
71
+ if (archive.invalidManifest)
72
+ throw new Error(
73
+ "Saved history could not be read. Open an intact copy of the source session.",
74
+ );
75
+ if (archive.archives.some((item) => !item.entries))
76
+ throw new Error(
77
+ "Archived history is unavailable in this session copy. Resume the source session.",
78
+ );
79
+ const seen = new Set<string>();
80
+ entries = [
81
+ ...archive.archives.flatMap((item) => item.entries ?? []),
82
+ ...entries,
83
+ ].filter((entry) => {
84
+ if (seen.has(entry.id)) return false;
85
+ seen.add(entry.id);
86
+ return true;
87
+ });
50
88
  let windowId = `session:${sessionId}`;
89
+ let activeStart = 0;
90
+ const positions = new Map(
91
+ entries.map((entry, position) => [entry.id, position]),
92
+ );
93
+ for (const [position, entry] of entries.entries()) {
94
+ const boundary = windowDetails(entry);
95
+ if (boundary?.kind === "window" && boundary.trim)
96
+ activeStart = position + 1;
97
+ if (entry.type === "compaction") {
98
+ const kept = positions.get(entry.firstKeptEntryId);
99
+ if (kept !== undefined && kept <= position)
100
+ activeStart = Math.max(activeStart, kept);
101
+ }
102
+ }
103
+ const retired = new Set(
104
+ entries.slice(0, activeStart).map((entry) => entry.id),
105
+ );
51
106
  const windows = new Map<string, HistoryItem[]>();
52
107
  windows.set(windowId, []);
53
- for (const entry of entries) {
108
+ for (const [position, entry] of entries.entries()) {
109
+ if (position % 512 === 0) {
110
+ await setImmediate();
111
+ signal?.throwIfAborted();
112
+ }
54
113
  const boundary = windowDetails(entry);
55
114
  if (boundary?.kind === "window") {
56
115
  windowId = boundary.identity.currentWindowId;
57
116
  if (!windows.has(windowId)) windows.set(windowId, []);
58
117
  continue;
59
118
  }
119
+ const cached = cachedItems.get(entry);
120
+ if (cached?.window_id === windowId) {
121
+ windows.get(windowId)!.push(cached);
122
+ continue;
123
+ }
124
+ let item: HistoryItem | undefined;
60
125
  if (entry.type === "message") {
61
126
  const message = entry.message;
62
127
  const call =
@@ -69,24 +134,26 @@ export function useHistory(
69
134
  : call?.type === "toolCall"
70
135
  ? call.name
71
136
  : undefined;
72
- const content = !("content" in message)
73
- ? JSON.stringify(message)
74
- : typeof message.content === "string"
75
- ? message.content
76
- : message.content
77
- .map((block) => {
78
- if (block.type === "text") return block.text;
79
- if (block.type === "thinking") return block.thinking;
80
- if (block.type === "toolCall")
81
- return JSON.stringify({
82
- tool: block.name,
83
- arguments: block.arguments,
84
- });
85
- if (block.type === "image") return `[image ${block.mimeType}]`;
86
- return JSON.stringify(block);
87
- })
88
- .join("\n");
89
- windows.get(windowId)!.push({
137
+ const render = () =>
138
+ !("content" in message)
139
+ ? JSON.stringify(message)
140
+ : typeof message.content === "string"
141
+ ? message.content
142
+ : message.content
143
+ .map((block) => {
144
+ if (block.type === "text") return block.text;
145
+ if (block.type === "thinking") return block.thinking;
146
+ if (block.type === "toolCall")
147
+ return JSON.stringify({
148
+ tool: block.name,
149
+ arguments: block.arguments,
150
+ });
151
+ if (block.type === "image")
152
+ return `[image ${block.mimeType}]`;
153
+ return JSON.stringify(block);
154
+ })
155
+ .join("\n");
156
+ item = {
90
157
  window_id: windowId,
91
158
  item_id: entry.id,
92
159
  role: message.role === "toolResult" ? "tool" : message.role,
@@ -98,24 +165,100 @@ export function useHistory(
98
165
  : {}),
99
166
  }
100
167
  : {}),
101
- content,
102
- });
168
+ get content() {
169
+ return content(entry, render);
170
+ },
171
+ };
172
+ if (message.role === "user" || message.role === "assistant") {
173
+ const body = message.content;
174
+ const hasText =
175
+ typeof body === "string"
176
+ ? body.length > 0
177
+ : body.some(
178
+ (block) => block.type === "text" && block.text.length > 0,
179
+ );
180
+ let indexedContent: string | undefined;
181
+ if (hasText)
182
+ indexItems.set(item, {
183
+ item_id: item.item_id,
184
+ get content() {
185
+ return (indexedContent ??=
186
+ typeof body === "string"
187
+ ? body
188
+ : body
189
+ .filter((block) => block.type === "text")
190
+ .map((block) => block.text)
191
+ .join("\n"));
192
+ },
193
+ });
194
+ }
103
195
  } else if (entry.type === "custom_message" && !boundary) {
104
- windows.get(windowId)!.push({
196
+ item = {
105
197
  window_id: windowId,
106
198
  item_id: entry.id,
107
199
  role: customHistoryRole(entry),
108
- content:
109
- typeof entry.content === "string"
110
- ? entry.content
111
- : entry.content
112
- .map((block) =>
113
- block.type === "text" ? block.text : "[image]",
114
- )
115
- .join("\n"),
116
- });
200
+ get content() {
201
+ return content(entry, () =>
202
+ typeof entry.content === "string"
203
+ ? entry.content
204
+ : entry.content
205
+ .map((block) =>
206
+ block.type === "text" ? block.text : "[image]",
207
+ )
208
+ .join("\n"),
209
+ );
210
+ },
211
+ };
212
+ }
213
+ if (item) {
214
+ cachedItems.set(entry, item);
215
+ windows.get(windowId)!.push(item);
117
216
  }
118
217
  }
218
+ return { windows, retired };
219
+ }
220
+
221
+ export async function indexHistory(
222
+ entries: readonly SessionEntry[],
223
+ sessionId: string,
224
+ search: HistorySearch,
225
+ allEntries: readonly SessionEntry[] = entries,
226
+ ): Promise<void> {
227
+ if (!search.isEnabled(sessionId)) return;
228
+ const { windows, retired } = await historyWindows(
229
+ entries,
230
+ sessionId,
231
+ allEntries,
232
+ );
233
+ const items = [...windows.values()].flat();
234
+ await search.index(
235
+ sessionId,
236
+ items
237
+ .filter((item) => retired.has(item.item_id))
238
+ .flatMap((item) => indexItems.get(item) ?? []),
239
+ undefined,
240
+ items
241
+ .filter((item) => !retired.has(item.item_id) || !indexItems.has(item))
242
+ .map((item) => item.item_id),
243
+ );
244
+ }
245
+
246
+ export async function useHistory(
247
+ entries: readonly SessionEntry[],
248
+ params: Record<string, unknown>,
249
+ sessionId: string,
250
+ search: HistorySearch,
251
+ allEntries: readonly SessionEntry[] = entries,
252
+ signal?: AbortSignal,
253
+ liveAccess = false,
254
+ ): Promise<Record<string, unknown>> {
255
+ signal?.throwIfAborted();
256
+ const { windows, retired } = await historyWindows(
257
+ entries,
258
+ sessionId,
259
+ allEntries,
260
+ signal,
261
+ );
119
262
  const action = params["action"];
120
263
  if (action === "list_windows") {
121
264
  let values = [...windows].filter(([, items]) => items.length);
@@ -129,14 +272,13 @@ export function useHistory(
129
272
  };
130
273
  }
131
274
  if (action === "read_item") {
132
- if (
133
- typeof params["window_id"] !== "string" ||
134
- typeof params["item_id"] !== "string"
135
- )
136
- throw new Error("Supply window_id and item_id unchanged from history");
137
- const item = windows
138
- .get(params["window_id"])
139
- ?.find((item) => item.item_id === params["item_id"]);
275
+ const windowId = params["window_id"];
276
+ const itemId = params["item_id"];
277
+ if (typeof windowId !== "string" || typeof itemId !== "string")
278
+ throw new Error(
279
+ `history read_item requires ${typeof windowId !== "string" ? "window_id" : "item_id"} as a string. Copy window_id and item_id from the same search_contents or list_items result`,
280
+ );
281
+ const item = windows.get(windowId)?.find((item) => item.item_id === itemId);
140
282
  if (!item) return { item: null };
141
283
  const offset = integer(params["offset_chars"], 0, item.content.length);
142
284
  const limit = integer(params["limit_chars"], 8000, 8000);
@@ -159,6 +301,7 @@ export function useHistory(
159
301
  (typeof params["query"] !== "string" || !params["query"])
160
302
  )
161
303
  throw new Error("Supply a nonempty search query");
304
+ const limit = integer(params["limit"], 10, 25);
162
305
  let items = [...windows.values()]
163
306
  .flat()
164
307
  .filter(
@@ -167,12 +310,38 @@ export function useHistory(
167
310
  (!params["role"] || item.role === params["role"]) &&
168
311
  (!params["tool_name"] || item.tool_name === params["tool_name"]) &&
169
312
  (!params["tool_namespace"] ||
170
- item.tool_namespace === params["tool_namespace"]) &&
171
- (action !== "search_contents" ||
172
- item.content.includes(params["query"] as string)),
313
+ item.tool_namespace === params["tool_namespace"]),
173
314
  );
174
- if (params["recent_first"] === true) items = items.reverse();
175
- const limit = integer(params["limit"], 10, 25);
315
+ const ranked =
316
+ search.isEnabled(sessionId) &&
317
+ !liveAccess &&
318
+ !params["agent_name"] &&
319
+ (!params["role"] ||
320
+ params["role"] === "user" ||
321
+ params["role"] === "assistant") &&
322
+ !params["tool_name"] &&
323
+ !params["tool_namespace"] &&
324
+ (!params["window_id"] || items.every((item) => retired.has(item.item_id)));
325
+ if (action === "search_contents" && ranked) {
326
+ const canonical = new Map(items.map((item) => [item.item_id, item]));
327
+ const matches = await search.search(
328
+ sessionId,
329
+ items
330
+ .filter((item) => retired.has(item.item_id))
331
+ .flatMap((item) => indexItems.get(item) ?? []),
332
+ params["query"] as string,
333
+ limit,
334
+ params["recent_first"] === true,
335
+ signal,
336
+ );
337
+ items = matches.map((item) => canonical.get(item.item_id)!);
338
+ } else {
339
+ if (action === "search_contents")
340
+ items = items.filter((item) =>
341
+ item.content.includes(params["query"] as string),
342
+ );
343
+ if (params["recent_first"] === true) items = items.reverse();
344
+ }
176
345
  const previewChars = integer(params["max_chars_per_item"], 1000, 1000);
177
346
  const previews = [];
178
347
  let size = 0;
@@ -196,3 +365,5 @@ function integer(value: unknown, fallback: number, max: number): number {
196
365
  ? Math.max(0, Math.min(value, max))
197
366
  : fallback;
198
367
  }
368
+
369
+ import { setImmediate } from "node:timers/promises";
@@ -0,0 +1,201 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type {
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ InputEvent,
6
+ InputEventResult,
7
+ } from "@earendil-works/pi-coding-agent";
8
+ import type { NotesLifecycle } from "./lifecycle.js";
9
+ import { SETTLEMENT_ENTRY } from "./windows.js";
10
+
11
+ interface HeldInput {
12
+ sessionId: string;
13
+ phase: "failed" | "rolling" | "releasing" | "draining";
14
+ releasePrompt: string;
15
+ admissions: ((result: InputEventResult) => void)[];
16
+ }
17
+
18
+ // Owns suspended input calls and custom-kickoff admission; reset settles held callers.
19
+ export class IdleAdmission {
20
+ private held: HeldInput | undefined;
21
+ private customAdmission: Promise<void> | undefined;
22
+ private readonly host: Pick<
23
+ NotesLifecycle,
24
+ "active" | "fresh" | "windows" | "idleMinutes"
25
+ >;
26
+ private readonly pi: ExtensionAPI;
27
+ private readonly roll: (
28
+ ctx: ExtensionContext,
29
+ triggerTurn: boolean,
30
+ ) => Promise<void>;
31
+ private readonly rolloverPending: () => boolean;
32
+ private readonly checkpointPending: () => boolean;
33
+ constructor(
34
+ host: IdleAdmission["host"],
35
+ pi: ExtensionAPI,
36
+ roll: IdleAdmission["roll"],
37
+ rolloverPending: () => boolean,
38
+ checkpointPending: () => boolean,
39
+ ) {
40
+ this.host = host;
41
+ this.pi = pi;
42
+ this.roll = roll;
43
+ this.rolloverPending = rolloverPending;
44
+ this.checkpointPending = checkpointPending;
45
+ }
46
+ get pending(): boolean {
47
+ return Boolean(this.held);
48
+ }
49
+ reset(): void {
50
+ this.customAdmission = undefined;
51
+ for (const admit of this.held?.admissions ?? [])
52
+ admit({ action: "handled" });
53
+ this.held = undefined;
54
+ }
55
+ fail(ctx: ExtensionContext, error: unknown): void {
56
+ if (this.held) this.failHeld(ctx, this.held, error);
57
+ }
58
+ drain(): boolean {
59
+ if (this.held?.phase !== "draining") return false;
60
+ // Retry admissions are original SDK calls too. Releasing all at once races Agent.prompt.
61
+ this.held.phase = "releasing";
62
+ this.pi.sendUserMessage(this.held.releasePrompt);
63
+ return true;
64
+ }
65
+
66
+ prepareCustomTurn(ctx: ExtensionContext): Promise<void> | undefined {
67
+ if (this.customAdmission) return this.customAdmission;
68
+ if (!this.host.active || !this.idleDue(ctx) || !this.host.fresh(ctx))
69
+ return;
70
+ const sessionId = ctx.sessionManager.getSessionId();
71
+ const preparation = this.roll(ctx, false)
72
+ .then(() => {
73
+ if (
74
+ !this.host.active ||
75
+ sessionId !== ctx.sessionManager.getSessionId()
76
+ )
77
+ throw new Error("Session changed during custom kickoff admission");
78
+ })
79
+ .finally(() => {
80
+ if (this.customAdmission === preparation)
81
+ this.customAdmission = undefined;
82
+ });
83
+ this.customAdmission = preparation;
84
+ return preparation;
85
+ }
86
+ private idleDue(ctx: ExtensionContext): boolean {
87
+ if (
88
+ this.host.idleMinutes === 0 ||
89
+ !ctx.isIdle() ||
90
+ !this.host.windows.current ||
91
+ this.rolloverPending() ||
92
+ this.checkpointPending()
93
+ )
94
+ return false;
95
+ const branch = ctx.sessionManager.getBranch();
96
+ const terminal = branch.findLast(
97
+ (entry) => entry.type === "message" && entry.message.role !== "system",
98
+ );
99
+ if (!terminal) return false;
100
+ const settlement = ctx.sessionManager
101
+ .getEntries()
102
+ .findLast(
103
+ (entry) =>
104
+ entry.type === "custom" &&
105
+ entry.customType === SETTLEMENT_ENTRY &&
106
+ entry.data &&
107
+ typeof entry.data === "object" &&
108
+ "completedEntryId" in entry.data &&
109
+ entry.data.completedEntryId === terminal.id,
110
+ );
111
+ if (
112
+ settlement?.type !== "custom" ||
113
+ !settlement.data ||
114
+ typeof settlement.data !== "object"
115
+ )
116
+ return false;
117
+ const data = settlement.data;
118
+ return (
119
+ !("aborted" in data && data.aborted === true) &&
120
+ "windowId" in data &&
121
+ data.windowId === this.host.windows.current.currentWindowId &&
122
+ "settledAt" in data &&
123
+ typeof data.settledAt === "number" &&
124
+ Number.isFinite(data.settledAt) &&
125
+ Date.now() - data.settledAt >= this.host.idleMinutes * 60_000
126
+ );
127
+ }
128
+ async input(
129
+ event: InputEvent,
130
+ ctx: ExtensionContext,
131
+ ): Promise<InputEventResult | undefined> {
132
+ const releasing = this.held;
133
+ if (
134
+ releasing?.phase === "releasing" &&
135
+ event.source === "extension" &&
136
+ event.text === releasing.releasePrompt
137
+ ) {
138
+ const admit = releasing.admissions.shift();
139
+ if (releasing.admissions.length) releasing.phase = "draining";
140
+ else this.held = undefined;
141
+ admit?.({ action: "continue" });
142
+ return { action: "handled" };
143
+ }
144
+ if (!this.held && (!this.idleDue(ctx) || !this.host.fresh(ctx))) return;
145
+ const held =
146
+ this.held ??
147
+ ({
148
+ sessionId: ctx.sessionManager.getSessionId(),
149
+ phase: "failed",
150
+ releasePrompt: `Admit saved input: ${randomUUID()}`,
151
+ admissions: [],
152
+ } satisfies HeldInput);
153
+ this.held = held;
154
+ const admission = new Promise<InputEventResult>((resolve) =>
155
+ held.admissions.push(resolve),
156
+ );
157
+ if (held.phase !== "failed") return admission;
158
+ held.phase = "rolling";
159
+ void Promise.resolve().then(async () => {
160
+ try {
161
+ if (
162
+ this.held !== held ||
163
+ held.sessionId !== ctx.sessionManager.getSessionId()
164
+ )
165
+ return;
166
+ await this.finishHeld(ctx, held);
167
+ } catch (error) {
168
+ this.failHeld(ctx, held, error);
169
+ }
170
+ });
171
+ return admission;
172
+ }
173
+ private failHeld(
174
+ ctx: ExtensionContext,
175
+ held: HeldInput,
176
+ error: unknown,
177
+ ): void {
178
+ if (this.held !== held) return;
179
+ held.phase = "failed";
180
+ ctx.ui.notify(
181
+ `Idle rollover failed: ${error instanceof Error ? error.message : String(error)}. Input and attachments remain pending. Submit another prompt to retry, or reload to cancel.`,
182
+ "error",
183
+ );
184
+ }
185
+ private async finishHeld(
186
+ ctx: ExtensionContext,
187
+ held: HeldInput,
188
+ ): Promise<void> {
189
+ held.phase = "rolling";
190
+ await this.roll(ctx, false);
191
+ if (
192
+ this.held !== held ||
193
+ held.sessionId !== ctx.sessionManager.getSessionId()
194
+ )
195
+ return;
196
+ held.phase = "releasing";
197
+ // Pi defers this user kickoff until EVERY agent_settled handler returns.
198
+ // Its input-only admission releases the original SDK calls, preserving images/options.
199
+ this.pi.sendUserMessage(held.releasePrompt);
200
+ }
201
+ }