@howaboua/pi-notes-compaction 0.0.14 → 0.0.16

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 (83) hide show
  1. package/CHANGELOG.md +21 -1
  2. package/LICENSE +21 -0
  3. package/README.md +8 -3
  4. package/index.ts +8 -0
  5. package/package.json +16 -11
  6. package/src/board/context-briefing.ts +245 -0
  7. package/src/board/delivery.ts +85 -0
  8. package/src/guidance.ts +121 -0
  9. package/src/notes/AGENTS.md +27 -0
  10. package/src/{activation.ts → notes/activation.ts} +8 -10
  11. package/src/{attachment-sharing.ts → notes/attachment-sharing.ts} +1 -1
  12. package/src/{attachment-snapshot.ts → notes/attachment-snapshot.ts} +33 -20
  13. package/src/{bridge.ts → notes/bridge.ts} +1 -0
  14. package/src/{context-sharing.ts → notes/context-sharing.ts} +22 -2
  15. package/src/{extension-hooks.ts → notes/extension-hooks.ts} +1 -12
  16. package/src/{extension-sharing.ts → notes/extension-sharing.ts} +2 -1
  17. package/src/notes/feature.ts +168 -0
  18. package/src/{history-windows.ts → notes/history-windows.ts} +10 -22
  19. package/src/{history.ts → notes/history.ts} +6 -5
  20. package/src/{index.ts → notes/index.ts} +20 -11
  21. package/src/{integrations.ts → notes/integrations.ts} +19 -3
  22. package/src/{lifecycle.ts → notes/lifecycle.ts} +0 -2
  23. package/src/{note-query.ts → notes/note-query.ts} +3 -5
  24. package/src/notes/note-result.ts +119 -0
  25. package/src/{note-save-marker.ts → notes/note-save-marker.ts} +3 -1
  26. package/src/{query-executor.ts → notes/query-executor.ts} +34 -9
  27. package/src/{query-input.ts → notes/query-input.ts} +1 -0
  28. package/src/{remote.ts → notes/remote.ts} +1 -1
  29. package/src/notes/saved-session-access.ts +121 -0
  30. package/src/notes/saved-session-index.mjs +83 -0
  31. package/src/notes/saved-session.mjs +241 -0
  32. package/src/notes/saved-session.ts +67 -0
  33. package/src/notes/saved-sharing-records.ts +170 -0
  34. package/src/{session-pruning.ts → notes/session-pruning.ts} +5 -5
  35. package/src/{settings-command.ts → notes/settings-command.ts} +29 -42
  36. package/src/{settings-controls.ts → notes/settings-controls.ts} +62 -72
  37. package/src/{settings-screen.ts → notes/settings-screen.ts} +25 -7
  38. package/src/{settings.ts → notes/settings.ts} +37 -6
  39. package/src/notes/shared-notes.ts +419 -0
  40. package/src/{shared-session-reader.ts → notes/shared-session-reader.ts} +35 -26
  41. package/src/{sharing-service.ts → notes/sharing-service.ts} +32 -1
  42. package/src/{store.ts → notes/store.ts} +10 -0
  43. package/src/{tool-contracts.ts → notes/tool-contracts.ts} +71 -44
  44. package/src/{tools.ts → notes/tools.ts} +2 -2
  45. package/src/notes/tree-archive-manifest.mjs +27 -0
  46. package/src/{tree-archive.ts → notes/tree-archive.ts} +6 -26
  47. package/src/{tree-handoff-read.ts → notes/tree-handoff-read.ts} +47 -32
  48. package/src/{window-message.ts → notes/window-message.ts} +15 -20
  49. package/src/settings-navigation.ts +11 -0
  50. package/src/timestamps.ts +3 -0
  51. package/tsconfig.json +9 -0
  52. package/src/note-result.ts +0 -70
  53. package/src/saved-session.ts +0 -169
  54. package/src/saved-sharing-records.ts +0 -112
  55. package/src/shared-notes.ts +0 -290
  56. /package/src/{agent-identity.ts → notes/agent-identity.ts} +0 -0
  57. /package/src/{binding-startup.ts → notes/binding-startup.ts} +0 -0
  58. /package/src/{compaction-projection.ts → notes/compaction-projection.ts} +0 -0
  59. /package/src/{context-owner.ts → notes/context-owner.ts} +0 -0
  60. /package/src/{fresh-checkpoint.ts → notes/fresh-checkpoint.ts} +0 -0
  61. /package/src/{fresh-notes.ts → notes/fresh-notes.ts} +0 -0
  62. /package/src/{history-search-protocol.ts → notes/history-search-protocol.ts} +0 -0
  63. /package/src/{history-search-pruning.mjs → notes/history-search-pruning.mjs} +0 -0
  64. /package/src/{history-search-worker.mjs → notes/history-search-worker.mjs} +0 -0
  65. /package/src/{history-search.ts → notes/history-search.ts} +0 -0
  66. /package/src/{idle-admission.ts → notes/idle-admission.ts} +0 -0
  67. /package/src/{model-role-config.ts → notes/model-role-config.ts} +0 -0
  68. /package/src/{model-role-screen.ts → notes/model-role-screen.ts} +0 -0
  69. /package/src/{model-roles.ts → notes/model-roles.ts} +0 -0
  70. /package/src/{notes-lookup.ts → notes/notes-lookup.ts} +0 -0
  71. /package/src/{notes.ts → notes/notes.ts} +0 -0
  72. /package/src/{rollover.ts → notes/rollover.ts} +0 -0
  73. /package/src/{session-pruning-content.ts → notes/session-pruning-content.ts} +0 -0
  74. /package/src/{session-pruning-plan.ts → notes/session-pruning-plan.ts} +0 -0
  75. /package/src/{session-pruning-policy.ts → notes/session-pruning-policy.ts} +0 -0
  76. /package/src/{session-pruning-screen.ts → notes/session-pruning-screen.ts} +0 -0
  77. /package/src/{session-pruning-source.ts → notes/session-pruning-source.ts} +0 -0
  78. /package/src/{session-pruning-transaction.ts → notes/session-pruning-transaction.ts} +0 -0
  79. /package/src/{sqlite.mjs → notes/sqlite.mjs} +0 -0
  80. /package/src/{task-boundary.ts → notes/task-boundary.ts} +0 -0
  81. /package/src/{tree-checkpoint.ts → notes/tree-checkpoint.ts} +0 -0
  82. /package/src/{window-checkpoint.ts → notes/window-checkpoint.ts} +0 -0
  83. /package/src/{windows.ts → notes/windows.ts} +0 -0
@@ -0,0 +1,119 @@
1
+ import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
2
+ import {
3
+ arr,
4
+ bool,
5
+ compile,
6
+ int,
7
+ nul,
8
+ obj,
9
+ opt,
10
+ str,
11
+ union,
12
+ unsafe,
13
+ } from "@earendil-works/pi-schema";
14
+
15
+ const OPTIONAL_STRING = opt(str());
16
+ const OPTIONAL_BOOLEAN = opt(bool());
17
+ const MATCH = obj({ line_number: int(), line: str() }, { open: true });
18
+
19
+ // Pi codemode needs this declaration to return structuredContent rather than text.
20
+ export const NOTES_OUTPUT_SCHEMA = {
21
+ ...obj({}, { open: true }),
22
+ additionalProperties: true,
23
+ };
24
+
25
+ const NOTES_RESULT_SCHEMA = obj(
26
+ {
27
+ file: opt(
28
+ union([
29
+ obj(
30
+ {
31
+ path: str(),
32
+ content: OPTIONAL_STRING,
33
+ append_only: OPTIONAL_BOOLEAN,
34
+ },
35
+ { open: true },
36
+ ),
37
+ nul(),
38
+ ]),
39
+ ),
40
+ files: opt(
41
+ arr(
42
+ obj(
43
+ {
44
+ path: str(),
45
+ updated_at: OPTIONAL_STRING,
46
+ created_at: OPTIONAL_STRING,
47
+ matches: opt(arr(MATCH)),
48
+ truncated: OPTIONAL_BOOLEAN,
49
+ append_only: OPTIONAL_BOOLEAN,
50
+ },
51
+ { open: true },
52
+ ),
53
+ ),
54
+ ),
55
+ usage: OPTIONAL_STRING,
56
+ warnings: opt(arr(str())),
57
+ warning: OPTIONAL_STRING,
58
+ truncated: OPTIONAL_BOOLEAN,
59
+ read_only: OPTIONAL_BOOLEAN,
60
+ saved_at: OPTIONAL_STRING,
61
+ captured_at: OPTIONAL_STRING,
62
+ results: OPTIONAL_STRING,
63
+ actions: opt(
64
+ unsafe<Record<string, string>>({
65
+ type: "object",
66
+ patternProperties: { "^.*$": str() },
67
+ }),
68
+ ),
69
+ writes: OPTIONAL_STRING,
70
+ paths: OPTIONAL_STRING,
71
+ ranges: OPTIONAL_STRING,
72
+ defaults: OPTIONAL_STRING,
73
+ },
74
+ { open: false },
75
+ );
76
+
77
+ const notesResultSchemaValidator = compile(NOTES_RESULT_SCHEMA);
78
+
79
+ /** One canonical payload for native text and every programmatic caller. */
80
+ export function noteResult(payload: unknown): AgentToolResult<unknown> {
81
+ if (!notesResultSchemaValidator.check(payload))
82
+ throw new Error(
83
+ "Notes returned invalid data. Read the note before retrying a write.",
84
+ );
85
+ // Keep recovery warnings, but omit sharing and storage bookkeeping.
86
+ const {
87
+ read_only: _readOnly,
88
+ warning,
89
+ saved_at: _savedAt,
90
+ captured_at: _capturedAt,
91
+ ...visible
92
+ } = payload;
93
+ if (warning !== undefined)
94
+ visible.warnings = [...(visible.warnings ?? []), warning];
95
+ if (visible.file)
96
+ visible.file = {
97
+ path: visible.file.path,
98
+ ...(visible.file.content === undefined
99
+ ? {}
100
+ : { content: visible.file.content }),
101
+ ...(visible.file.append_only === undefined
102
+ ? {}
103
+ : { append_only: visible.file.append_only }),
104
+ };
105
+ if (visible.files)
106
+ visible.files = visible.files.map(
107
+ ({ path, matches, truncated, append_only }) => ({
108
+ path,
109
+ ...(matches === undefined ? {} : { matches }),
110
+ ...(truncated === undefined ? {} : { truncated }),
111
+ ...(append_only === undefined ? {} : { append_only }),
112
+ }),
113
+ );
114
+ return {
115
+ content: [{ type: "text", text: JSON.stringify(visible) }],
116
+ structuredContent: visible,
117
+ details: {},
118
+ };
119
+ }
@@ -25,7 +25,6 @@ export function registerNoteSaveMarkers(
25
25
  manager = ctx.sessionManager;
26
26
  cached = undefined;
27
27
  };
28
- pi.on("session_start", restore);
29
28
  pi.on("session_tree", restore);
30
29
  pi.on("session_compact", restore);
31
30
  pi.on("session_shutdown", () => {
@@ -63,6 +62,9 @@ export function registerNoteSaveMarkers(
63
62
  })("", 0, 0);
64
63
  });
65
64
  return {
65
+ start(ctx: ExtensionContext) {
66
+ restore(undefined, ctx);
67
+ },
66
68
  record(
67
69
  ctx: ExtensionContext,
68
70
  windowId: string | undefined,
@@ -53,6 +53,21 @@ export function createQueryExecutor(
53
53
  assertActive();
54
54
  const raw = queryArguments("notes", input);
55
55
  if (!shared) {
56
+ let unavailable: unknown;
57
+ try {
58
+ const saved = await readSharedNotes(
59
+ ctx,
60
+ store,
61
+ raw,
62
+ signal,
63
+ lifecycle.bridge?.loadSavedSession,
64
+ );
65
+ if (saved) return noteResult(saved);
66
+ } catch (error) {
67
+ signal?.throwIfAborted();
68
+ if (!sharedNotesUnavailable(error)) throw error;
69
+ unavailable = error;
70
+ }
56
71
  try {
57
72
  const routed = await lifecycle.bridge?.route?.(
58
73
  { namespace: "notes", params: raw },
@@ -60,16 +75,18 @@ export function createQueryExecutor(
60
75
  ctx,
61
76
  signal,
62
77
  );
63
- if (routed) return routed;
78
+ if (routed)
79
+ return {
80
+ ...routed,
81
+ ...noteResult(routed.structuredContent),
82
+ details: routed.details,
83
+ };
64
84
  } catch (error) {
65
85
  signal?.throwIfAborted();
66
- if (!sharedNotesUnavailable(error)) throw error;
67
- const saved = await readSharedNotes(ctx, store, raw, signal);
68
- if (saved) return noteResult(saved);
69
- throw error;
86
+ if (!unavailable || !sharedNotesUnavailable(error)) throw error;
87
+ throw unavailable;
70
88
  }
71
- const saved = await readSharedNotes(ctx, store, raw, signal);
72
- if (saved) return noteResult(saved);
89
+ if (unavailable) throw unavailable;
73
90
  }
74
91
  const identity = contextAgentIdentity(ctx);
75
92
  const storageAgent = contextStorageAgentName(identity);
@@ -184,11 +201,19 @@ export function createQueryExecutor(
184
201
  search,
185
202
  params,
186
203
  signal,
204
+ lifecycle.bridge?.loadSavedSession,
187
205
  );
188
206
  if (saved) return result(saved);
189
207
  throw error;
190
208
  }
191
- const saved = await readSharedHistory(ctx, store, search, params, signal);
209
+ const saved = await readSharedHistory(
210
+ ctx,
211
+ store,
212
+ search,
213
+ params,
214
+ signal,
215
+ lifecycle.bridge?.loadSavedSession,
216
+ );
192
217
  if (saved) return result(saved);
193
218
  }
194
219
  if (
@@ -198,7 +223,7 @@ export function createQueryExecutor(
198
223
  )
199
224
  )
200
225
  throw new Error(
201
- "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.",
226
+ "That agent's history is unavailable here. Omit agent_name to search this session, or request an accessible handoff from its owner.",
202
227
  );
203
228
  signal?.throwIfAborted();
204
229
  return result(
@@ -69,6 +69,7 @@ export function normalizeQueryInput(
69
69
  if (action !== undefined) params["action"] = action;
70
70
  if (namespace === "notes") {
71
71
  alias(params, "address", "path");
72
+ if (action === "read") alias(params, "end_line", "stop_line");
72
73
  if (action === "write" || action === "append") {
73
74
  alias(params, "content", "text");
74
75
  alias(params, "body", "text");
@@ -278,7 +278,7 @@ export async function executeRemoteAttachment(
278
278
  reference,
279
279
  );
280
280
  return {
281
- ...noteResult({ usage: "Saved remote read completed" }),
281
+ ...noteResult({}),
282
282
  details: {
283
283
  codexHistoryNotes: {},
284
284
  externalNotesResponses: responses.map(({ bytes, ...response }) => ({
@@ -0,0 +1,121 @@
1
+ import { arr, compile, obj, str } from "@earendil-works/pi-schema";
2
+ import type {
3
+ SavedSessionLoader,
4
+ SavedSessionLocator,
5
+ } from "./context-sharing.js";
6
+ import {
7
+ readSavedNotesSession,
8
+ type SavedNotesSession,
9
+ validateSavedNotesSession,
10
+ } from "./saved-session.js";
11
+ import { savedFamilyIdentity } from "./saved-sharing-records.js";
12
+ import type { NotesStore } from "./store.js";
13
+
14
+ const Locations = arr(
15
+ obj(
16
+ {
17
+ machine: str({ minLength: 1 }),
18
+ sessionFile: str({ minLength: 1 }),
19
+ },
20
+ { open: true },
21
+ ),
22
+ );
23
+
24
+ const locationsValidator = compile(Locations);
25
+
26
+ /** Local is relative to the session carrying the edge, not the machine running this reader. */
27
+ export function createSavedSessionAccess(
28
+ store: Pick<NotesStore, "sessionFile">,
29
+ namespace: "notes" | "history",
30
+ loader: SavedSessionLoader | undefined,
31
+ signal: AbortSignal | undefined,
32
+ ) {
33
+ const locations = new WeakMap<SavedNotesSession, SavedSessionLocator>();
34
+ const containingMachine = (session: SavedNotesSession) =>
35
+ locations.get(session)?.machine ?? "local";
36
+ function locator(
37
+ session: SavedNotesSession,
38
+ machine: string,
39
+ sessionFile: string,
40
+ ): SavedSessionLocator {
41
+ return {
42
+ machine: machine === "local" ? containingMachine(session) : machine,
43
+ sessionFile,
44
+ };
45
+ }
46
+ async function load(
47
+ location: SavedSessionLocator,
48
+ ): Promise<SavedNotesSession> {
49
+ signal?.throwIfAborted();
50
+ const session =
51
+ location.machine === "local"
52
+ ? await readSavedNotesSession(
53
+ location.sessionFile,
54
+ signal,
55
+ namespace === "history",
56
+ )
57
+ : loader
58
+ ? validateSavedNotesSession(
59
+ await loader(location, namespace === "history", signal),
60
+ )
61
+ : (() => {
62
+ throw Object.assign(
63
+ new Error(
64
+ "Saved context on that machine is unavailable. Request a handoff from its owner, or ask the user to reconnect the machine before retrying.",
65
+ ),
66
+ { code: "SAVED_SESSION_UNAVAILABLE" },
67
+ );
68
+ })();
69
+ locations.set(session, location);
70
+ return session;
71
+ }
72
+
73
+ async function indexed(
74
+ current: SavedNotesSession,
75
+ target: string,
76
+ ): Promise<SavedNotesSession | undefined> {
77
+ // An exact local hint avoids dead relay parents. Index rows never establish membership.
78
+ const family = savedFamilyIdentity(current);
79
+ const threadId = target.slice(1);
80
+ if (family && !threadId.includes("/") && target !== "/root") {
81
+ const file = store.sessionFile(threadId);
82
+ if (file) {
83
+ const saved = await load({ machine: "local", sessionFile: file });
84
+ const member = savedFamilyIdentity(saved);
85
+ if (
86
+ saved.threadId !== threadId ||
87
+ !member ||
88
+ member.storage !== "session" ||
89
+ member.sessionId !== family.sessionId ||
90
+ member.agentName !== target
91
+ )
92
+ throw new Error(
93
+ "This session cannot access the requested saved context. Request an accessible handoff or note path from its owner.",
94
+ );
95
+ return saved;
96
+ }
97
+ }
98
+ return;
99
+ }
100
+ async function find(target: string): Promise<SavedSessionLocator[]> {
101
+ const threadId = target.slice(1);
102
+ if (!loader?.find || target === "/root" || threadId.includes("/"))
103
+ return [];
104
+ signal?.throwIfAborted();
105
+ const value = await loader.find(threadId, signal);
106
+ signal?.throwIfAborted();
107
+ if (!locationsValidator.check(value))
108
+ throw new Error(
109
+ "Saved session discovery response is invalid. Update Notes on the other machine and retry.",
110
+ );
111
+ return [
112
+ ...new Map(
113
+ value.map((location) => [
114
+ `${location.machine}\0${location.sessionFile}`,
115
+ location,
116
+ ]),
117
+ ).values(),
118
+ ];
119
+ }
120
+ return { containingMachine, locator, load, indexed, find };
121
+ }
@@ -0,0 +1,83 @@
1
+ import { readdir, stat } from "node:fs/promises";
2
+ import { createRequire } from "node:module";
3
+ import { homedir } from "node:os";
4
+ import { join, resolve } from "node:path";
5
+
6
+ /** Exact path hints only. Neither the index nor a filename establishes Notes membership.
7
+ * Missing indexes are normal for old sessions; other index failures are reported.
8
+ * @param {string} threadId
9
+ * @param {string} [agentDir]
10
+ * @param {AbortSignal} [signal]
11
+ * @returns {Promise<string[]>}
12
+ */
13
+ export async function findSavedNotesSessions(threadId, agentDir, signal) {
14
+ signal?.throwIfAborted();
15
+ if (
16
+ !/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(threadId) ||
17
+ threadId === "root"
18
+ )
19
+ throw new Error("Invalid saved session thread ID");
20
+ const configured =
21
+ agentDir ??
22
+ process.env["PI_CODING_AGENT_DIR"] ??
23
+ join(homedir(), ".pi", "agent");
24
+ const dir =
25
+ configured === "~" || configured.startsWith("~/")
26
+ ? join(homedir(), configured.slice(2))
27
+ : resolve(configured);
28
+ const paths = new Set();
29
+ const index = join(dir, "notes-compaction", "notes.sqlite");
30
+ try {
31
+ await stat(index);
32
+ /** @type {import("node:sqlite").DatabaseSync} */
33
+ const db = process.versions["bun"]
34
+ ? new (createRequire(import.meta.url)("bun:sqlite").Database)(index, {
35
+ readonly: true,
36
+ })
37
+ : new (await import("node:sqlite")).DatabaseSync(index, {
38
+ readOnly: true,
39
+ });
40
+ try {
41
+ signal?.throwIfAborted();
42
+ const table = db
43
+ .prepare(
44
+ "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'sessions'",
45
+ )
46
+ .get();
47
+ if (table) {
48
+ const row = db
49
+ .prepare("SELECT file_path FROM sessions WHERE id = ?")
50
+ .get(threadId);
51
+ if (row && typeof row["file_path"] === "string" && row["file_path"])
52
+ paths.add(row["file_path"]);
53
+ }
54
+ } finally {
55
+ db.close();
56
+ }
57
+ } catch (error) {
58
+ signal?.throwIfAborted();
59
+ if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
60
+ throw new Error(
61
+ "Saved session index is unavailable. Restore access to the Notes index and retry.",
62
+ { cause: error },
63
+ );
64
+ }
65
+ const sessions = join(dir, "sessions");
66
+ try {
67
+ for (const cwd of await readdir(sessions, { withFileTypes: true })) {
68
+ signal?.throwIfAborted();
69
+ if (!cwd.isDirectory()) continue;
70
+ const directory = join(sessions, cwd.name);
71
+ for (const file of await readdir(directory, { withFileTypes: true })) {
72
+ signal?.throwIfAborted();
73
+ if (file.isFile() && file.name.endsWith(`_${threadId}.jsonl`))
74
+ paths.add(join(directory, file.name));
75
+ }
76
+ }
77
+ } catch (error) {
78
+ signal?.throwIfAborted();
79
+ if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
80
+ throw error;
81
+ }
82
+ return [...paths].sort();
83
+ }
@@ -0,0 +1,241 @@
1
+ import { createHash } from "node:crypto";
2
+ import { open, stat } from "node:fs/promises";
3
+ import {
4
+ isTreeArchiveManifestData,
5
+ MAX_ARCHIVE_DEPTH,
6
+ TREE_ARCHIVE_ENTRY_TYPE,
7
+ } from "./tree-archive-manifest.mjs";
8
+
9
+ /** @param {unknown} value @returns {value is Record<string, unknown>} */
10
+ function object(value) {
11
+ return value !== null && typeof value === "object" && !Array.isArray(value);
12
+ }
13
+ /** @param {unknown} value @returns {value is {type:"session",id:string}} */
14
+ function isSessionHeader(value) {
15
+ return (
16
+ object(value) &&
17
+ value["type"] === "session" &&
18
+ typeof value["id"] === "string"
19
+ );
20
+ }
21
+ /** @param {unknown} value @returns {value is import("@earendil-works/pi-coding-agent").SessionEntry} */
22
+ function isRecord(value) {
23
+ return (
24
+ object(value) &&
25
+ typeof value["type"] === "string" &&
26
+ typeof value["id"] === "string" &&
27
+ (value["parentId"] === null || typeof value["parentId"] === "string") &&
28
+ typeof value["timestamp"] === "string"
29
+ );
30
+ }
31
+ /** @param {unknown} value @returns {value is import("@earendil-works/pi-coding-agent").CustomEntry} */
32
+ function isCustom(value) {
33
+ return (
34
+ isRecord(value) &&
35
+ value.type === "custom" &&
36
+ typeof value.customType === "string" &&
37
+ "data" in value
38
+ );
39
+ }
40
+ /** @param {unknown} value @returns {value is import("@earendil-works/pi-coding-agent").BranchSummaryEntry} */
41
+ function isHandoff(value) {
42
+ return (
43
+ isRecord(value) &&
44
+ value.type === "branch_summary" &&
45
+ typeof value.fromId === "string" &&
46
+ typeof value.summary === "string" &&
47
+ object(value.details) &&
48
+ "codexContextNoteHandoff" in value.details
49
+ );
50
+ }
51
+ const NOTE_ENTRIES = new Set([
52
+ "notes-compaction:note:v1",
53
+ "notes-compaction:cache:v1",
54
+ "codex-context-note",
55
+ "codex-context-note-snapshot",
56
+ ]);
57
+ const SHARING_ENTRIES = new Set([
58
+ "codex-context-agent",
59
+ "codex-context-backend",
60
+ "herdr-context-child",
61
+ "shepherdr-attachment-route",
62
+ "shepherdr-attachment-owner",
63
+ "shepherdr-attachment-detached",
64
+ ]);
65
+
66
+ /** @param {import("node:fs/promises").FileHandle} file @param {number} size @param {AbortSignal} [signal] */
67
+ async function* reverseChunks(file, size, signal) {
68
+ let position = size;
69
+ while (position > 0) {
70
+ signal?.throwIfAborted();
71
+ const length = Math.min(64 * 1024, position);
72
+ position -= length;
73
+ const chunk = Buffer.allocUnsafe(length);
74
+ let offset = 0;
75
+ while (offset < length) {
76
+ const { bytesRead } = await file.read(
77
+ chunk,
78
+ offset,
79
+ length - offset,
80
+ position + offset,
81
+ );
82
+ if (!bytesRead)
83
+ throw new Error(
84
+ "Saved notes changed during the read. Retry the lookup.",
85
+ );
86
+ offset += bytesRead;
87
+ }
88
+ yield chunk;
89
+ }
90
+ }
91
+
92
+ /** @param {import("node:fs/promises").FileHandle} file @param {number} size @param {import("node:crypto").Hash} hash @param {AbortSignal} [signal] */
93
+ async function* reverseLines(file, size, hash, signal) {
94
+ /** @type {Buffer[]} */
95
+ let parts = [];
96
+ for await (const chunk of reverseChunks(file, size, signal)) {
97
+ hash.update(chunk);
98
+ let end = chunk.length;
99
+ for (let index = chunk.length - 1; index >= 0; index--) {
100
+ if (chunk[index] !== 10) continue;
101
+ const tail = chunk.subarray(index + 1, end);
102
+ // Long JSONL records span many chunks. Scan each byte once and join
103
+ // fragments only at the newline, rather than recopying a growing line.
104
+ if (parts.length) {
105
+ parts.push(tail);
106
+ yield Buffer.concat(parts.reverse());
107
+ parts = [];
108
+ } else yield tail;
109
+ end = index;
110
+ }
111
+ if (end) parts.push(chunk.subarray(0, end));
112
+ }
113
+ yield Buffer.concat(parts.reverse());
114
+ }
115
+
116
+ /** Read only recorded session paths. Identity is session-wide; notes follow the active parent chain. */
117
+ /** @param {string} path @param {AbortSignal} [signal] @param {boolean} [history] @returns {Promise<import("./saved-session.js").SavedNotesSession>} */
118
+ export async function readSavedNotesSession(path, signal, history = false) {
119
+ signal?.throwIfAborted();
120
+ const file = await open(path, "r");
121
+ try {
122
+ const before = await file.stat();
123
+ const hash = createHash("sha256");
124
+ /** @type {import("@earendil-works/pi-coding-agent").SessionEntry[]} */
125
+ const entries = [];
126
+ /** @type {import("@earendil-works/pi-coding-agent").SessionEntry[]} */
127
+ const branch = [];
128
+ /** @type {Map<string, {base:string|null,depth:number}[]>} */
129
+ const archived = new Map();
130
+ /** @type {string | undefined} */
131
+ let threadId;
132
+ /** @type {string | null | undefined} */
133
+ let target;
134
+ for await (const line of reverseLines(file, before.size, hash, signal)) {
135
+ signal?.throwIfAborted();
136
+ if (!line.length) continue;
137
+ /** @type {unknown} */
138
+ let entry;
139
+ try {
140
+ entry = JSON.parse(line.toString("utf8"));
141
+ } catch {
142
+ throw new Error(
143
+ "Saved notes are being updated. Retry after the session settles.",
144
+ );
145
+ }
146
+ if (isSessionHeader(entry)) {
147
+ threadId = entry.id;
148
+ continue;
149
+ }
150
+ if (!isRecord(entry)) throw new Error("Invalid saved session record");
151
+ if (target === undefined) target = entry.id;
152
+ const active = entry.id === target;
153
+ if (active) target = entry.parentId;
154
+ if (history) {
155
+ // Pi appends descendants after their parents, including Tree manifests
156
+ // after their archived leaves. Follow only active manifests' ancestry.
157
+ const paths = archived.get(entry.id) ?? [];
158
+ archived.delete(entry.id);
159
+ for (const path of paths) {
160
+ if (++path.depth >= MAX_ARCHIVE_DEPTH || entry.parentId === path.base)
161
+ continue;
162
+ if (entry.parentId !== null) {
163
+ const parents = archived.get(entry.parentId) ?? [];
164
+ parents.push(path);
165
+ archived.set(entry.parentId, parents);
166
+ }
167
+ }
168
+ if (
169
+ active &&
170
+ isCustom(entry) &&
171
+ entry.customType === TREE_ARCHIVE_ENTRY_TYPE &&
172
+ isTreeArchiveManifestData(entry.data) &&
173
+ entry.data.archivedLeafId !== entry.data.branchBaseId
174
+ ) {
175
+ const paths = archived.get(entry.data.archivedLeafId) ?? [];
176
+ paths.push({ base: entry.data.branchBaseId, depth: 0 });
177
+ archived.set(entry.data.archivedLeafId, paths);
178
+ }
179
+ if (
180
+ active ||
181
+ paths.length ||
182
+ (isCustom(entry) && SHARING_ENTRIES.has(entry.customType))
183
+ )
184
+ entries.push(entry);
185
+ if (active) branch.push(entry);
186
+ continue;
187
+ }
188
+ if (isCustom(entry)) {
189
+ if (SHARING_ENTRIES.has(entry.customType)) entries.push(entry);
190
+ else if (active && NOTE_ENTRIES.has(entry.customType))
191
+ branch.push(entry);
192
+ else continue;
193
+ } else if (active && isHandoff(entry)) branch.push(entry);
194
+ else continue;
195
+ }
196
+ // Pruning replaces the path. An open descriptor alone still sees the old inode.
197
+ const after = await stat(path);
198
+ if (
199
+ after.dev !== before.dev ||
200
+ after.ino !== before.ino ||
201
+ after.size < before.size ||
202
+ (after.size === before.size &&
203
+ (after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs))
204
+ )
205
+ throw new Error("Saved notes changed during the read. Retry the lookup.");
206
+ if (after.size > before.size) {
207
+ // Flushed Pi sessions append. Keep the original leaf/byte boundary,
208
+ // but prove its prefix did not change, including abandoned identities.
209
+ // Hash the same reverse chunks, without retaining the whole JSONL.
210
+ const verified = createHash("sha256");
211
+ for await (const chunk of reverseChunks(file, before.size, signal))
212
+ verified.update(chunk);
213
+ if (hash.digest("hex") !== verified.digest("hex"))
214
+ throw new Error(
215
+ "Saved notes changed during the read. Retry the lookup.",
216
+ );
217
+ const current = await stat(path);
218
+ if (
219
+ current.dev !== before.dev ||
220
+ current.ino !== before.ino ||
221
+ current.size < after.size ||
222
+ (current.size === after.size &&
223
+ (current.mtimeMs !== after.mtimeMs ||
224
+ current.ctimeMs !== after.ctimeMs))
225
+ )
226
+ throw new Error(
227
+ "Saved notes changed during the read. Retry the lookup.",
228
+ );
229
+ }
230
+ if (!threadId || (target !== undefined && target !== null))
231
+ throw new Error("Saved notes have an incomplete session branch");
232
+ return {
233
+ threadId,
234
+ entries: entries.reverse(),
235
+ branch: branch.reverse(),
236
+ savedAt: before.mtimeMs,
237
+ };
238
+ } finally {
239
+ await file.close();
240
+ }
241
+ }