@howaboua/pi-notes-compaction 0.0.9 → 0.0.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 (54) hide show
  1. package/CHANGELOG.md +28 -5
  2. package/PCC-INTEGRATION.md +7 -98
  3. package/README.md +21 -13
  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 +258 -0
  20. package/src/history-search.ts +269 -0
  21. package/src/history.ts +212 -40
  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 +24 -28
  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 +204 -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 +155 -0
  40. package/src/settings-command.ts +77 -0
  41. package/src/settings-screen.ts +84 -19
  42. package/src/settings.ts +143 -11
  43. package/src/shared-notes.ts +37 -14
  44. package/src/sharing-service.ts +348 -0
  45. package/src/sqlite.mjs +33 -0
  46. package/src/store.ts +46 -13
  47. package/src/task-boundary.ts +6 -1
  48. package/src/tool-contracts.ts +279 -0
  49. package/src/tools.ts +19 -560
  50. package/src/tree-archive.ts +149 -0
  51. package/src/tree-checkpoint.ts +170 -0
  52. package/src/tree-handoff-read.ts +192 -0
  53. package/src/window-checkpoint.ts +105 -0
  54. package/src/windows.ts +25 -9
@@ -0,0 +1,112 @@
1
+ import type {
2
+ ExtensionAPI,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
5
+ import { Text } from "@earendil-works/pi-tui";
6
+ import { hasFreshNotes } from "./fresh-notes.js";
7
+
8
+ const NOTE_SAVE_MARKER = "codex-note-save-marker";
9
+
10
+ /** Display and bookmarks share the same completed checkpoint evidence. */
11
+ export function registerNoteSaveMarkers(
12
+ pi: ExtensionAPI,
13
+ enabled: () => boolean,
14
+ ) {
15
+ let manager: ExtensionContext["sessionManager"] | undefined;
16
+ let cached: { leaf: string | null; id: string | undefined } | undefined;
17
+ const restore = (_event: unknown, ctx: ExtensionContext) => {
18
+ manager = ctx.sessionManager;
19
+ cached = undefined;
20
+ };
21
+ pi.on("session_start", restore);
22
+ pi.on("session_tree", restore);
23
+ pi.on("session_compact", restore);
24
+ pi.on("session_shutdown", () => {
25
+ manager = undefined;
26
+ cached = undefined;
27
+ });
28
+ pi.registerEntryRenderer(NOTE_SAVE_MARKER, (entry, _options, theme) => {
29
+ if (!enabled()) return undefined;
30
+ const content = theme.fg("success", "✓ Notes saved");
31
+ return new (class extends Text {
32
+ override render(width: number): string[] {
33
+ const leaf = manager?.getLeafId();
34
+ if (manager && (!cached || cached.leaf !== leaf))
35
+ cached = {
36
+ leaf: manager.getLeafId(),
37
+ id: manager
38
+ .getBranch()
39
+ .findLast(
40
+ (item) =>
41
+ item.type === "custom" &&
42
+ item.customType === NOTE_SAVE_MARKER,
43
+ )?.id,
44
+ };
45
+ const visible = manager && enabled() && cached?.id === entry.id;
46
+ this.setText(visible ? content : "");
47
+ return visible ? super.render(width) : [];
48
+ }
49
+ })("", 0, 0);
50
+ });
51
+ return {
52
+ record(
53
+ ctx: ExtensionContext,
54
+ windowId: string | undefined,
55
+ runId: string,
56
+ aborted: boolean,
57
+ ) {
58
+ if (
59
+ !enabled() ||
60
+ aborted ||
61
+ !ctx.isIdle() ||
62
+ !hasFreshNotes(ctx.sessionManager.getBranch(), windowId, runId)
63
+ )
64
+ return;
65
+ const completed = ctx.sessionManager
66
+ .getBranch()
67
+ .findLast(
68
+ (entry) =>
69
+ entry.type === "message" && entry.message.role === "assistant",
70
+ );
71
+ if (
72
+ !completed ||
73
+ ctx.sessionManager
74
+ .getEntries()
75
+ .some(
76
+ (entry) =>
77
+ entry.type === "custom" &&
78
+ entry.customType === NOTE_SAVE_MARKER &&
79
+ entry.data &&
80
+ typeof entry.data === "object" &&
81
+ "completedEntryId" in entry.data &&
82
+ entry.data.completedEntryId === completed.id,
83
+ )
84
+ )
85
+ return;
86
+ pi.appendEntry(NOTE_SAVE_MARKER, { completedEntryId: completed.id });
87
+ },
88
+ bookmark(ctx: ExtensionContext, windowId: string | undefined) {
89
+ if (!enabled()) return;
90
+ const branch = ctx.sessionManager.getBranch();
91
+ const marker = branch.findLastIndex(
92
+ (entry) =>
93
+ entry.type === "custom" && entry.customType === NOTE_SAVE_MARKER,
94
+ );
95
+ if (marker < 0) return;
96
+ const promptIndex = branch.findIndex(
97
+ (entry, index) =>
98
+ index > marker &&
99
+ entry.type === "message" &&
100
+ entry.message.role === "user",
101
+ );
102
+ const prompt = branch[promptIndex];
103
+ if (
104
+ !prompt ||
105
+ ctx.sessionManager.getLabel(prompt.id) ||
106
+ !hasFreshNotes(branch.slice(0, promptIndex), windowId)
107
+ )
108
+ return;
109
+ pi.setLabel(prompt.id, "Notes");
110
+ },
111
+ };
112
+ }
@@ -0,0 +1,112 @@
1
+ import type {
2
+ AgentToolResult,
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import type {
7
+ CachedResponse,
8
+ LookupQuery,
9
+ SerializedCachedResponse,
10
+ } from "./bridge.js";
11
+ import { queryKey } from "./bridge.js";
12
+ import type { NotesLifecycle } from "./lifecycle.js";
13
+ import { CACHE_RECEIPT, sessionRef, sourceSessionIds } from "./notes.js";
14
+ import type { NotesStore } from "./store.js";
15
+ import { result } from "./tool-contracts.js";
16
+
17
+ export async function lookupNotes(
18
+ pi: ExtensionAPI,
19
+ store: NotesStore,
20
+ lifecycle: NotesLifecycle,
21
+ query: LookupQuery,
22
+ local: Record<string, unknown>,
23
+ callId: string,
24
+ ctx: ExtensionContext,
25
+ signal?: AbortSignal,
26
+ shared = false,
27
+ replacementsInScope = false,
28
+ ): Promise<AgentToolResult<unknown>> {
29
+ let responses: readonly CachedResponse[] = store.cached(
30
+ sourceSessionIds(ctx),
31
+ query,
32
+ );
33
+ let state = responses.length ? "cache" : "unavailable";
34
+ let lookupFailed = false;
35
+ const bridge = lifecycle.bridge;
36
+ if (bridge?.lookup) {
37
+ let fetched: readonly CachedResponse[] | undefined;
38
+ try {
39
+ fetched = await bridge.lookup(query, ctx, signal);
40
+ } catch (error) {
41
+ if (signal?.aborted) throw error;
42
+ lookupFailed = true;
43
+ }
44
+ if (signal?.aborted) throw new Error("Lookup cancelled");
45
+ if (fetched) {
46
+ try {
47
+ store.cache(sessionRef(ctx), fetched);
48
+ } catch {
49
+ throw new Error(
50
+ "Notes lookup could not finish. Retry when local storage is available.",
51
+ );
52
+ }
53
+ if (fetched.length)
54
+ pi.appendEntry(CACHE_RECEIPT, {
55
+ protocol: 1,
56
+ sessionId: ctx.sessionManager.getSessionId(),
57
+ });
58
+ const exact = fetched.filter(
59
+ (response) => queryKey(response.query) === queryKey(query),
60
+ );
61
+ if (exact.length) {
62
+ responses = exact;
63
+ state = "live";
64
+ }
65
+ }
66
+ }
67
+ const canProject =
68
+ shared ||
69
+ (Boolean(bridge?.projectResult) && bridge?.canProject?.(ctx) !== false);
70
+ if (responses.length && !canProject) state = "incompatible";
71
+ const warnings: string[] = [];
72
+ if (state === "incompatible")
73
+ warnings.push(
74
+ "Some notes cannot be read with this model. Available notes are shown; ask the user to select a compatible Codex model to read the rest.",
75
+ );
76
+ else if (state === "cache")
77
+ warnings.push(
78
+ "These results could not be refreshed and may be outdated. Retry when access is restored.",
79
+ );
80
+ else if (lookupFailed)
81
+ warnings.push(
82
+ "Some notes could not be retrieved. Available notes are shown; retry the lookup to check for missing results.",
83
+ );
84
+ if (responses.length && canProject && replacementsInScope)
85
+ warnings.push(
86
+ "Older matches may refer to replaced notes. Read a note before relying on its excerpt; read_file returns the current saved version.",
87
+ );
88
+ const output = result({ ...local, ...(warnings.length ? { warnings } : {}) });
89
+ if (shared)
90
+ return {
91
+ ...output,
92
+ details: {
93
+ codexHistoryNotes: {},
94
+ externalNotesResponses: responses.map(
95
+ ({ bytes, ...response }): SerializedCachedResponse => ({
96
+ ...response,
97
+ bytesBase64: Buffer.from(bytes).toString("base64"),
98
+ }),
99
+ ),
100
+ },
101
+ };
102
+ if (responses.length && canProject && bridge?.projectResult) {
103
+ try {
104
+ return await bridge.projectResult(output, responses, callId, ctx, signal);
105
+ } catch {
106
+ throw new Error(
107
+ "Notes could not be displayed. Retry the lookup with a compatible Codex model.",
108
+ );
109
+ }
110
+ }
111
+ return output;
112
+ }
package/src/notes.ts CHANGED
@@ -137,7 +137,7 @@ export function collectNotes(
137
137
  const receipt = noteReceipt(entry.data);
138
138
  if (!receipt)
139
139
  throw new Error(
140
- "A saved note receipt is invalid. Open an intact session branch to recover notes.",
140
+ "A saved note could not be read. Open an intact session branch to recover it.",
141
141
  );
142
142
  // A fork carries the receipt even when its source session was explicitly pruned.
143
143
  const revision = store.read(receipt.revision.id) ?? receipt.revision;
@@ -347,18 +347,18 @@ export function readNotes(
347
347
  if (action === "read_file") {
348
348
  const path = params["path"] as string;
349
349
  const note = notes.get(path);
350
- if (!note) return { source: "pi-session", file: null };
350
+ if (!note) return { file: null };
351
351
  const lines = note.text.split("\n");
352
352
  const start = lineIndex(params["start_line"], lines.length, 0);
353
353
  const stop = lineIndex(params["stop_line"], lines.length, lines.length - 1);
354
354
  return {
355
- source: "pi-session",
356
355
  file: {
357
- ...noteMetadata(note, root),
356
+ path: `${root}${note.path}`,
358
357
  content: start <= stop ? lines.slice(start, stop + 1).join("\n") : "",
359
358
  start_line: start + 1,
360
359
  stop_line: Math.max(start, stop) + 1,
361
360
  total_lines: lines.length,
361
+ ...(note.mode === "append" ? { append_only: true } : {}),
362
362
  },
363
363
  };
364
364
  }
@@ -375,9 +375,18 @@ export function readNotes(
375
375
  ? a.updatedAt - b.updatedAt
376
376
  : a.path.localeCompare(b.path)) * direction,
377
377
  )
378
- .slice(0, integer(params["max_results"], 20, 100))
379
- .map((note) => noteMetadata(note, root));
380
- return { source: "pi-session", files };
378
+ .map((note) => ({
379
+ path: `${root}${note.path}`,
380
+ updated_at: new Date(note.updatedAt).toISOString(),
381
+ ...(by === "created_at"
382
+ ? { created_at: new Date(note.createdAt).toISOString() }
383
+ : {}),
384
+ }));
385
+ const limit = integer(params["max_results"], 20, 100);
386
+ return {
387
+ files: files.slice(0, limit),
388
+ ...(files.length > limit ? { truncated: true } : {}),
389
+ };
381
390
  }
382
391
  if (action !== "search_contents")
383
392
  throw new Error("notes requires a supported action");
@@ -393,36 +402,23 @@ export function readNotes(
393
402
  : (a, b) => a.path.localeCompare(b.path),
394
403
  );
395
404
  const found: Record<string, unknown>[] = [];
405
+ const fileLimit = integer(params["max_files"], 20, 100);
406
+ const matchLimit = integer(params["max_matches_per_file"], 20, 100);
396
407
  for (const note of files) {
397
408
  const matches = note.text
398
409
  .split("\n")
399
410
  .map((line, index) => ({ line_number: index + 1, line }))
400
- .filter(({ line }) => line.includes(query))
401
- .slice(0, integer(params["max_matches_per_file"], 20, 100));
411
+ .filter(({ line }) => line.includes(query));
402
412
  if (!matches.length) continue;
413
+ if (found.length === fileLimit) return { files: found, truncated: true };
403
414
  found.push({
404
415
  path: `${root}${note.path}`,
405
- matches,
406
- operation:
407
- note.mode === "replace" ? "local_replacement" : "local_append_overlay",
416
+ matches: matches.slice(0, matchLimit),
417
+ ...(matches.length > matchLimit ? { truncated: true } : {}),
418
+ ...(note.mode === "append" ? { append_only: true } : {}),
408
419
  });
409
- if (found.length >= integer(params["max_files"], 20, 100)) break;
410
420
  }
411
- return { source: "pi-session", files: found };
412
- }
413
-
414
- function noteMetadata(
415
- note: NoteRevision,
416
- root: string,
417
- ): Record<string, unknown> {
418
- return {
419
- operation:
420
- note.mode === "replace" ? "local_replacement" : "local_append_overlay",
421
- path: `${root}${note.path}`,
422
- bytes: Buffer.byteLength(note.text, "utf8"),
423
- created_at: new Date(note.createdAt).toISOString(),
424
- updated_at: new Date(note.updatedAt).toISOString(),
425
- };
421
+ return { files: found };
426
422
  }
427
423
 
428
424
  function lineIndex(
@@ -0,0 +1,190 @@
1
+ import type {
2
+ AgentToolResult,
3
+ ExtensionAPI,
4
+ ExtensionContext,
5
+ } from "@earendil-works/pi-coding-agent";
6
+ import { useHistory } from "./history.js";
7
+ import type { HistorySearch } from "./history-search.js";
8
+ import type { NotesLifecycle } from "./lifecycle.js";
9
+ import { collectNotes, normalizeNoteParams, useNotes } from "./notes.js";
10
+ import { lookupNotes } from "./notes-lookup.js";
11
+ import {
12
+ readSharedHistory,
13
+ readSharedNotes,
14
+ sharedNotesUnavailable,
15
+ } from "./shared-notes.js";
16
+ import type { NotesStore } from "./store.js";
17
+ import { queryArguments, queryHelp, result } from "./tool-contracts.js";
18
+
19
+ export function createQueryExecutor(
20
+ pi: ExtensionAPI,
21
+ store: NotesStore,
22
+ lifecycle: NotesLifecycle,
23
+ search: HistorySearch,
24
+ shared = false,
25
+ ) {
26
+ const assertActive = () => {
27
+ if (!lifecycle.active && !shared)
28
+ throw new Error(
29
+ "Notes tools are inactive. Ask the user to check /notes.",
30
+ );
31
+ };
32
+ async function notes(
33
+ callId: string,
34
+ input: unknown,
35
+ signal: AbortSignal | undefined,
36
+ ctx: ExtensionContext,
37
+ ): Promise<AgentToolResult<unknown>> {
38
+ const help = queryHelp("notes", input);
39
+ if (help) return help;
40
+ assertActive();
41
+ const raw = queryArguments("notes", input);
42
+ if (!shared) {
43
+ try {
44
+ const routed = await lifecycle.bridge?.route?.(
45
+ { namespace: "notes", params: raw },
46
+ callId,
47
+ ctx,
48
+ signal,
49
+ );
50
+ if (routed) return routed;
51
+ } catch (error) {
52
+ signal?.throwIfAborted();
53
+ if (!sharedNotesUnavailable(error)) throw error;
54
+ const saved = await readSharedNotes(ctx, store, raw, signal);
55
+ if (saved) return result(saved);
56
+ throw error;
57
+ }
58
+ const saved = await readSharedNotes(ctx, store, raw, signal);
59
+ if (saved) return result(saved);
60
+ }
61
+ const params = queryArguments(
62
+ "notes",
63
+ normalizeNoteParams(raw, lifecycle.agent(ctx)),
64
+ );
65
+ if (signal?.aborted) throw new Error("Note operation cancelled");
66
+ const local = useNotes(
67
+ pi,
68
+ store,
69
+ params,
70
+ ctx,
71
+ lifecycle.agent(ctx),
72
+ lifecycle.windows.current?.currentWindowId ?? "",
73
+ lifecycle.runId,
74
+ shared,
75
+ );
76
+ if (
77
+ params["action"] === "write_file" ||
78
+ params["action"] === "append_to_file"
79
+ )
80
+ return {
81
+ ...result(local),
82
+ details: {
83
+ ...(shared
84
+ ? { codexHistoryNotes: {}, notesCompactionRouted: true }
85
+ : {
86
+ notesCompaction: {
87
+ protocol: 1,
88
+ saved: true,
89
+ runId: lifecycle.runId,
90
+ },
91
+ }),
92
+ },
93
+ };
94
+ const notes = collectNotes(store, ctx.sessionManager.getBranch());
95
+ if (
96
+ params["action"] === "read_file" &&
97
+ notes.get(params["path"] as string)?.mode === "replace"
98
+ )
99
+ return result(local);
100
+ const prefix = String(params["prefix"] ?? params["path_prefix"] ?? "");
101
+ const replacementsInScope =
102
+ params["action"] !== "read_file" &&
103
+ [...notes.values()].some(
104
+ (note) => note.mode === "replace" && note.path.startsWith(prefix),
105
+ );
106
+ const remoteParams = { ...params };
107
+ for (const field of ["path", "prefix", "path_prefix"])
108
+ if (typeof remoteParams[field] === "string")
109
+ remoteParams[field] =
110
+ `${lifecycle.agent(ctx)}/notes${remoteParams[field] ? `/${remoteParams[field]}` : ""}`;
111
+ return lookupNotes(
112
+ pi,
113
+ store,
114
+ lifecycle,
115
+ { namespace: "notes", params: remoteParams },
116
+ local,
117
+ callId,
118
+ ctx,
119
+ signal,
120
+ shared,
121
+ replacementsInScope,
122
+ );
123
+ }
124
+ async function history(
125
+ callId: string,
126
+ input: unknown,
127
+ signal: AbortSignal | undefined,
128
+ ctx: ExtensionContext,
129
+ ): Promise<AgentToolResult<unknown>> {
130
+ const help = queryHelp(
131
+ "history",
132
+ input,
133
+ search.isEnabled(ctx.sessionManager.getSessionId()),
134
+ lifecycle.gptPromptMode(),
135
+ );
136
+ if (help) return help;
137
+ assertActive();
138
+ const params = queryArguments("history", input);
139
+ if (!shared) {
140
+ try {
141
+ const routed = await lifecycle.bridge?.route?.(
142
+ { namespace: "history", params },
143
+ callId,
144
+ ctx,
145
+ signal,
146
+ );
147
+ if (routed) return routed;
148
+ } catch (error) {
149
+ signal?.throwIfAborted();
150
+ if (
151
+ !sharedNotesUnavailable(error) &&
152
+ !(
153
+ error instanceof Error &&
154
+ error.message ===
155
+ "Counterpart history requires its live attached owner; native history is unchanged"
156
+ )
157
+ )
158
+ throw error;
159
+ const saved = await readSharedHistory(
160
+ ctx,
161
+ store,
162
+ search,
163
+ params,
164
+ signal,
165
+ );
166
+ if (saved) return result(saved);
167
+ throw error;
168
+ }
169
+ const saved = await readSharedHistory(ctx, store, search, params, signal);
170
+ if (saved) return result(saved);
171
+ }
172
+ if (params["agent_name"] && params["agent_name"] !== lifecycle.agent(ctx))
173
+ throw new Error(
174
+ "That agent's Pi session history is unavailable on this machine. Restore access to its saved JSONL session, or omit agent_name to search this session.",
175
+ );
176
+ signal?.throwIfAborted();
177
+ return result(
178
+ await useHistory(
179
+ ctx.sessionManager.getBranch(),
180
+ params,
181
+ ctx.sessionManager.getSessionId(),
182
+ search,
183
+ ctx.sessionManager.getEntries(),
184
+ signal,
185
+ shared,
186
+ ),
187
+ );
188
+ }
189
+ return { notes, history };
190
+ }