@howaboua/pi-agent-comms 0.0.1 → 0.0.2

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.
@@ -0,0 +1,163 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import {
3
+ closeSync,
4
+ fsyncSync,
5
+ lstatSync,
6
+ openSync,
7
+ readdirSync,
8
+ renameSync,
9
+ statSync,
10
+ unlinkSync,
11
+ } from "node:fs";
12
+ import { open } from "node:fs/promises";
13
+ import { resolve } from "node:path";
14
+ import {
15
+ planSparsePruning,
16
+ scanSparseSource,
17
+ } from "./session-pruning-sparse.mjs";
18
+ import { cleanupPaths, tryCleanupLock } from "./session-pruning-state.mjs";
19
+
20
+ /** @param {string} path @param {import("node:fs").Stats} source */
21
+ function checkSource(path, source) {
22
+ const current = lstatSync(path);
23
+ if (
24
+ !current.isFile() ||
25
+ current.nlink !== 1 ||
26
+ current.dev !== source.dev ||
27
+ current.ino !== source.ino ||
28
+ current.size !== source.size ||
29
+ current.mtimeMs !== source.mtimeMs ||
30
+ current.ctimeMs !== source.ctimeMs
31
+ )
32
+ throw new Error(
33
+ "Session changed during cleanup. Nothing was replaced. Cleanup will retry on the next normal Pi exit.",
34
+ );
35
+ }
36
+
37
+ /** Open descriptors supplement the registered session owners, not replace them.
38
+ * @param {import("node:fs").Stats} source
39
+ */
40
+ function checkHolders(source) {
41
+ if (process.platform !== "linux")
42
+ throw new Error(
43
+ "Automatic session cleanup is unavailable on this platform. Retired payloads remain pruned.",
44
+ );
45
+ const holders = new Set();
46
+ for (const pid of readdirSync("/proc")) {
47
+ if (!/^\d+$/.test(pid) || Number(pid) === process.pid) continue;
48
+ const dir = `/proc/${pid}`;
49
+ try {
50
+ if (statSync(dir).uid !== process.getuid?.()) continue;
51
+ for (const fd of readdirSync(`${dir}/fd`)) {
52
+ try {
53
+ const file = statSync(`${dir}/fd/${fd}`);
54
+ if (file.dev === source.dev && file.ino === source.ino)
55
+ holders.add(pid);
56
+ } catch (error) {
57
+ if (!vanished(error)) throw error;
58
+ }
59
+ }
60
+ } catch (error) {
61
+ if (
62
+ error instanceof Error &&
63
+ "code" in error &&
64
+ (error.code === "EACCES" || error.code === "EPERM")
65
+ )
66
+ continue;
67
+ else if (!vanished(error))
68
+ throw new Error(
69
+ `Cannot inspect open holders for PID ${pid}: ${String(error)}`,
70
+ );
71
+ }
72
+ }
73
+ if (holders.size)
74
+ throw new Error(
75
+ `Session record cleanup was skipped because process(es) ${[...holders].join(", ")} still hold it open. It will retry on the next normal Pi exit.`,
76
+ );
77
+ }
78
+
79
+ /** @param {unknown} error */
80
+ function vanished(error) {
81
+ return (
82
+ error instanceof Error &&
83
+ "code" in error &&
84
+ (error.code === "ENOENT" || error.code === "ESRCH")
85
+ );
86
+ }
87
+
88
+ /** Called only by the after-exit worker.
89
+ * @param {string} file @param {string} sessionId @param {()=>void} checkOwners
90
+ */
91
+ export async function cleanSparseSession(file, sessionId, checkOwners) {
92
+ const path = resolve(file);
93
+ const source = lstatSync(path);
94
+ if (!source.isFile() || source.nlink !== 1)
95
+ throw new Error(
96
+ "Session record cleanup requires a regular session file without symbolic or hard links. Retired payloads remain pruned.",
97
+ );
98
+ checkOwners();
99
+ checkHolders(source);
100
+ const lock = cleanupPaths(path).lock;
101
+ let releaseLock;
102
+ const temp = `${path}.notes-prune-${randomUUID()}.tmp`;
103
+ /** @type {Awaited<ReturnType<typeof open>>|undefined} */
104
+ let output;
105
+ try {
106
+ releaseLock = tryCleanupLock(path);
107
+ if (!releaseLock)
108
+ throw new Error(
109
+ `Another session cleanup may be running. Only after verifying that none is active, remove the stale lock ${JSON.stringify(lock)}. Cleanup will retry on the next normal Pi exit. Do not remove an active cleanup's lock.`,
110
+ );
111
+ checkOwners();
112
+ const plan = await planSparsePruning(path, source.size);
113
+ if (plan.header.id !== sessionId)
114
+ throw new Error("Session identity changed. Cleanup was skipped.");
115
+ checkSource(path, source);
116
+ if (!plan.removed.size)
117
+ return { removed: 0, before: source.size, after: source.size };
118
+ output = await open(temp, "wx", source.mode & 0o777);
119
+ const target = output;
120
+ const generation = randomUUID();
121
+ await scanSparseSource(path, source.size, async (entry, raw) => {
122
+ if (plan.removed.has(entry.id)) return;
123
+ const parentId = plan.parents.get(entry.id) ?? null;
124
+ const replacement =
125
+ entry.type === "session"
126
+ ? {
127
+ ...entry,
128
+ notesPruning: { version: 1, sessionId: entry.id, generation },
129
+ }
130
+ : entry.parentId === parentId
131
+ ? entry
132
+ : { ...entry, parentId };
133
+ await target.writeFile(
134
+ `${replacement === entry ? raw : JSON.stringify(replacement)}\n`,
135
+ );
136
+ });
137
+ await output.sync();
138
+ await output.close();
139
+ output = undefined;
140
+ // No await from final holder/source validation through atomic replacement.
141
+ checkOwners();
142
+ checkHolders(source);
143
+ checkSource(path, source);
144
+ const after = statSync(temp).size;
145
+ renameSync(temp, path);
146
+ const directory = openSync(resolve(path, ".."), "r");
147
+ try {
148
+ fsyncSync(directory);
149
+ } finally {
150
+ closeSync(directory);
151
+ }
152
+ return { removed: plan.removed.size, before: source.size, after };
153
+ } finally {
154
+ await output?.close();
155
+ try {
156
+ unlinkSync(temp);
157
+ } catch (error) {
158
+ if (!vanished(error)) throw error;
159
+ } finally {
160
+ releaseLock?.();
161
+ }
162
+ }
163
+ }
@@ -0,0 +1,312 @@
1
+ import { spawn } from "node:child_process";
2
+ import { randomUUID } from "node:crypto";
3
+ import {
4
+ existsSync,
5
+ mkdirSync,
6
+ readdirSync,
7
+ readFileSync,
8
+ renameSync,
9
+ rmdirSync,
10
+ unlinkSync,
11
+ writeFileSync,
12
+ } from "node:fs";
13
+ import { hostname } from "node:os";
14
+ import { dirname, isAbsolute, join, resolve } from "node:path";
15
+ import { setTimeout } from "node:timers/promises";
16
+ import { fileURLToPath } from "node:url";
17
+ import { cleanSparseSession } from "./session-pruning-cleanup.mjs";
18
+ import {
19
+ cleanupHeader,
20
+ cleanupPaths,
21
+ tryCleanupLock,
22
+ } from "./session-pruning-state.mjs";
23
+
24
+ /** @typedef {{pid:number; host:string; start:string; sessionId:string}} Owner */
25
+ const host = hostname();
26
+
27
+ /** Linux start time prevents a recycled PID from impersonating an owner.
28
+ * @param {number} pid
29
+ */
30
+ function processStart(pid) {
31
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
32
+ return stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19] ?? "";
33
+ }
34
+
35
+ /** @param {Owner} owner */
36
+ function alive(owner) {
37
+ if (owner.host !== host) return true;
38
+ try {
39
+ return processStart(owner.pid) === owner.start;
40
+ } catch (error) {
41
+ if (missing(error)) return false;
42
+ throw error;
43
+ }
44
+ }
45
+
46
+ /** @param {unknown} error */
47
+ function missing(error) {
48
+ return (
49
+ error instanceof Error &&
50
+ "code" in error &&
51
+ (error.code === "ENOENT" || error.code === "ESRCH")
52
+ );
53
+ }
54
+
55
+ /** @param {unknown} value @returns {value is Owner} */
56
+ function isOwner(value) {
57
+ if (!value || typeof value !== "object") return false;
58
+ const data = /** @type {Record<string,unknown>} */ (value);
59
+ return (
60
+ Number.isSafeInteger(data["pid"]) &&
61
+ Number(data["pid"]) > 0 &&
62
+ typeof data["host"] === "string" &&
63
+ typeof data["start"] === "string" &&
64
+ data["start"].length > 0 &&
65
+ typeof data["sessionId"] === "string"
66
+ );
67
+ }
68
+
69
+ /** Keep a positive claim while a saved session has a live Notes runtime.
70
+ * @param {string|undefined} file @param {string} sessionId
71
+ * @returns {(()=>void)|undefined}
72
+ */
73
+ function registerCleanupOwner(file, sessionId) {
74
+ if (process.platform !== "linux" || !file || !existsSync(file)) return;
75
+ const owner = {
76
+ pid: process.pid,
77
+ host,
78
+ start: processStart(process.pid),
79
+ sessionId,
80
+ };
81
+ const directory = cleanupPaths(file).owners;
82
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
83
+ const entry = join(
84
+ directory,
85
+ `${encodeURIComponent(host)}-${owner.pid}-${owner.start}-${randomUUID()}.json`,
86
+ );
87
+ writeFileSync(entry, JSON.stringify(owner), { mode: 0o600 });
88
+ const release = () => {
89
+ try {
90
+ unlinkSync(entry);
91
+ } catch (error) {
92
+ if (!missing(error)) throw error;
93
+ }
94
+ try {
95
+ rmdirSync(directory);
96
+ } catch (error) {
97
+ if (
98
+ !missing(error) &&
99
+ !(
100
+ error instanceof Error &&
101
+ "code" in error &&
102
+ error.code === "ENOTEMPTY"
103
+ )
104
+ )
105
+ throw error;
106
+ }
107
+ };
108
+ const onExit = () => {
109
+ // A failed best-effort release remains a stale claim; the worker removes
110
+ // it only after proving this PID/start identity has ended.
111
+ try {
112
+ release();
113
+ } catch {
114
+ /* Never turn normal Pi exit into a cleanup failure. */
115
+ }
116
+ };
117
+ process.once("exit", onExit);
118
+ return () => {
119
+ process.off("exit", onExit);
120
+ release();
121
+ };
122
+ }
123
+
124
+ /** @param {unknown} header @param {string} sessionId */
125
+ function generation(header, sessionId) {
126
+ if (
127
+ !header ||
128
+ typeof header !== "object" ||
129
+ !("id" in header) ||
130
+ header.id !== sessionId
131
+ )
132
+ throw new Error("Session identity changed during startup.");
133
+ if (!("notesPruning" in header) || header.notesPruning === undefined) return;
134
+ const marker = header.notesPruning;
135
+ if (
136
+ !marker ||
137
+ typeof marker !== "object" ||
138
+ !("generation" in marker) ||
139
+ typeof marker.generation !== "string"
140
+ )
141
+ throw new Error("Session pruning generation could not be validated.");
142
+ return marker.generation;
143
+ }
144
+
145
+ /** The manager is loaded before extension hooks. Serialize claim establishment
146
+ * with cleanup, then detect a rewrite that won before this startup could claim.
147
+ * @param {string|undefined} file @param {string} sessionId @param {unknown} loadedHeader
148
+ */
149
+ export async function admitSessionCleanup(file, sessionId, loadedHeader) {
150
+ if (process.platform !== "linux" || !file || !existsSync(file)) return;
151
+ const deadline = Date.now() + 120_000;
152
+ let unlock = tryCleanupLock(file);
153
+ while (!unlock) {
154
+ if (Date.now() >= deadline)
155
+ throw new Error(
156
+ `Session cleanup did not release ${JSON.stringify(cleanupPaths(file).lock)}. Verify no cleanup is active before removing a stale lock, then restart Pi.`,
157
+ );
158
+ await setTimeout(25);
159
+ unlock = tryCleanupLock(file);
160
+ }
161
+ try {
162
+ const raw = cleanupHeader(file);
163
+ const release = registerCleanupOwner(file, sessionId);
164
+ return {
165
+ release,
166
+ stale: generation(raw, sessionId) !== generation(loadedHeader, sessionId),
167
+ };
168
+ } finally {
169
+ unlock();
170
+ }
171
+ }
172
+
173
+ /** Do not delete records from another live manager of this exact saved session.
174
+ * Unknown/foreign claims are intentionally conservative. Unregistered foreign
175
+ * JSONL writers are outside the extension's ownership, as with live pruning.
176
+ * @param {string} file
177
+ */
178
+ function checkOwners(file) {
179
+ const directory = cleanupPaths(file).owners;
180
+ let entries;
181
+ try {
182
+ entries = readdirSync(directory);
183
+ } catch (error) {
184
+ if (missing(error)) return;
185
+ throw error;
186
+ }
187
+ for (const name of entries) {
188
+ const path = join(directory, name);
189
+ let owner;
190
+ try {
191
+ owner = JSON.parse(readFileSync(path, "utf8"));
192
+ } catch (error) {
193
+ if (missing(error)) continue;
194
+ throw error;
195
+ }
196
+ if (!isOwner(owner))
197
+ throw new Error(
198
+ "Session cleanup found an unrecognised live-session claim. Retired payloads remain pruned.",
199
+ );
200
+ if (alive(owner))
201
+ throw new Error(
202
+ "Session record cleanup was skipped because another process still owns this session. It will retry when that session exits.",
203
+ );
204
+ try {
205
+ unlinkSync(path);
206
+ } catch (error) {
207
+ if (!missing(error)) throw error;
208
+ }
209
+ }
210
+ }
211
+
212
+ /** @param {string} path @param {string} sessionId */
213
+ export function previousCleanupFailure(path, sessionId) {
214
+ try {
215
+ const value = JSON.parse(readFileSync(path, "utf8"));
216
+ unlinkSync(path);
217
+ return value.sessionId === sessionId && typeof value.error === "string"
218
+ ? value.error
219
+ : undefined;
220
+ } catch (error) {
221
+ if (missing(error)) return;
222
+ throw error;
223
+ }
224
+ }
225
+
226
+ /** @param {string} path @param {string} sessionId @param {unknown} error */
227
+ export function recordCleanupFailure(path, sessionId, error) {
228
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
229
+ const temp = `${path}.${process.pid}.tmp`;
230
+ writeFileSync(
231
+ temp,
232
+ JSON.stringify({
233
+ sessionId,
234
+ timestamp: new Date().toISOString().slice(0, 16) + "Z",
235
+ error: error instanceof Error ? error.message : String(error),
236
+ }),
237
+ { mode: 0o600 },
238
+ );
239
+ renameSync(temp, path);
240
+ }
241
+
242
+ /** Schedule without holding Pi open; this worker does not touch the graph until
243
+ * the real owning process exits, not merely when shutdown hooks finish.
244
+ * @param {string} file @param {string} sessionId @param {string} statusPath
245
+ */
246
+ export async function scheduleSessionCleanup(file, sessionId, statusPath) {
247
+ if (!existsSync(file)) return;
248
+ if (process.platform !== "linux")
249
+ throw new Error(
250
+ "Automatic session record cleanup is unavailable on this platform. Retired payloads remain pruned.",
251
+ );
252
+ const owner = {
253
+ pid: process.pid,
254
+ host,
255
+ start: processStart(process.pid),
256
+ sessionId,
257
+ };
258
+ const child = spawn(
259
+ "node",
260
+ [fileURLToPath(import.meta.url), file, JSON.stringify(owner), statusPath],
261
+ {
262
+ detached: true,
263
+ stdio: "ignore",
264
+ windowsHide: true,
265
+ },
266
+ );
267
+ await new Promise((resolve, reject) => {
268
+ child.once("error", reject);
269
+ child.once("spawn", resolve);
270
+ });
271
+ child.unref();
272
+ }
273
+
274
+ /** @param {string} file @param {Owner} owner @param {string} statusPath */
275
+ async function afterExit(file, owner, statusPath) {
276
+ try {
277
+ const deadline = Date.now() + 120_000;
278
+ while (alive(owner)) {
279
+ if (Date.now() >= deadline)
280
+ throw new Error(
281
+ "Session record cleanup was skipped because Pi did not exit. It will retry on the next normal exit.",
282
+ );
283
+ await setTimeout(250);
284
+ }
285
+ await cleanSparseSession(file, owner.sessionId, () => checkOwners(file));
286
+ try {
287
+ unlinkSync(statusPath);
288
+ } catch (error) {
289
+ if (!missing(error)) throw error;
290
+ }
291
+ } catch (error) {
292
+ recordCleanupFailure(statusPath, owner.sessionId, error);
293
+ }
294
+ }
295
+
296
+ if (
297
+ process.argv[1] &&
298
+ resolve(process.argv[1]) === fileURLToPath(import.meta.url)
299
+ ) {
300
+ const [file, encoded, statusPath] = process.argv.slice(2);
301
+ const owner = encoded && JSON.parse(encoded);
302
+ if (
303
+ !file ||
304
+ !statusPath ||
305
+ !isAbsolute(statusPath) ||
306
+ !isOwner(owner) ||
307
+ owner.host !== host ||
308
+ process.platform !== "linux"
309
+ )
310
+ throw new Error("Invalid after-exit session cleanup request.");
311
+ await afterExit(file, owner, statusPath);
312
+ }
@@ -159,7 +159,7 @@ export async function openSessionPruningSettings(
159
159
  theme.bold(" Session auto-pruning"),
160
160
  "",
161
161
  ...wrap(
162
- "Runs once after a new context window's first completed turn commits its checkpoint. Settings follow this session on resume; new and forked sessions start Off. Forks made before restarting can retain unpruned history.",
162
+ `Retired payloads are pruned after a new window's first completed turn. ${process.platform === "linux" ? "Empty records are removed automatically after Pi exits." : "Physical record cleanup requires Linux."} Settings follow this session on resume; new and forked sessions start Off. Forks made before restarting can retain unpruned history.`,
163
163
  ),
164
164
  "",
165
165
  ...wrap(RESTART_NOTICE),
@@ -0,0 +1,133 @@
1
+ import { createReadStream } from "node:fs";
2
+ import { createInterface } from "node:readline";
3
+ import {
4
+ isTreeArchiveManifestData,
5
+ TREE_ARCHIVE_ENTRY_TYPE,
6
+ } from "./tree-archive-manifest.mjs";
7
+
8
+ /** @typedef {import("@earendil-works/pi-coding-agent").SessionEntry} SessionEntry */
9
+ /** @typedef {import("@earendil-works/pi-coding-agent").SessionHeader & {notesPruning?:{version:number;sessionId:string;generation:string}}} Header */
10
+
11
+ /** A finite complete source, never a live SessionManager.
12
+ * @param {string} path @param {number} size
13
+ * @param {(entry:SessionEntry|Header, raw:string)=>void|Promise<void>} visit
14
+ */
15
+ export async function scanSparseSource(path, size, visit) {
16
+ if (!size) throw new Error("Session file is empty.");
17
+ const input = createReadStream(path, { start: 0, end: size - 1 });
18
+ const lines = createInterface({ input, crlfDelay: Infinity });
19
+ let bytes = 0;
20
+ try {
21
+ for await (const raw of lines) {
22
+ bytes += Buffer.byteLength(raw) + 1;
23
+ const entry = JSON.parse(raw);
24
+ if (
25
+ !entry ||
26
+ typeof entry.id !== "string" ||
27
+ typeof entry.timestamp !== "string" ||
28
+ typeof entry.type !== "string" ||
29
+ (entry.type !== "session" &&
30
+ entry.parentId !== null &&
31
+ typeof entry.parentId !== "string")
32
+ )
33
+ throw new Error("Session contains an invalid record.");
34
+ await visit(entry, raw);
35
+ }
36
+ if (bytes !== size)
37
+ throw new Error("Session requires complete LF-delimited records.");
38
+ } finally {
39
+ lines.close();
40
+ input.destroy();
41
+ }
42
+ }
43
+
44
+ /** Remove only existing retired tombstones; retention/content decisions stay with
45
+ * live Notes pruning. Keep navigation anchors and supported structured references.
46
+ * @param {string} path @param {number} size
47
+ */
48
+ export async function planSparsePruning(path, size) {
49
+ /** @type {Map<string,string|null>} */
50
+ const parents = new Map();
51
+ /** @type {Map<string,number>} */
52
+ const children = new Map();
53
+ const removed = new Set();
54
+ const anchors = new Set();
55
+ /** @type {Header|undefined} */
56
+ let header;
57
+ let last;
58
+ await scanSparseSource(path, size, (entry) => {
59
+ if (entry.type === "session") {
60
+ if (header || parents.size || entry.version !== 3)
61
+ throw new Error("Session requires a single version 3 header first.");
62
+ header = entry;
63
+ return;
64
+ }
65
+ if (
66
+ !header ||
67
+ parents.has(entry.id) ||
68
+ (entry.parentId !== null && !parents.has(entry.parentId))
69
+ )
70
+ throw new Error(
71
+ "Session has duplicate IDs or invalid source-order ancestry.",
72
+ );
73
+ last = entry.id;
74
+ parents.set(entry.id, entry.parentId);
75
+ if (entry.parentId === null) anchors.add(entry.id);
76
+ else children.set(entry.parentId, (children.get(entry.parentId) ?? 0) + 1);
77
+ if (
78
+ entry.type === "custom" &&
79
+ entry.customType === "notes-compaction:pruned:v1"
80
+ )
81
+ removed.add(entry.id);
82
+ for (const id of references(entry)) anchors.add(id);
83
+ });
84
+ if (!header) throw new Error("Session header is missing.");
85
+ const marker = header.notesPruning;
86
+ if (
87
+ marker !== undefined &&
88
+ (!marker ||
89
+ marker.version !== 1 ||
90
+ marker.sessionId !== header.id ||
91
+ typeof marker.generation !== "string")
92
+ )
93
+ throw new Error(
94
+ "The saved session has an invalid pruning generation. Session cleanup was skipped.",
95
+ );
96
+ if (last) anchors.add(last);
97
+ for (const id of parents.keys()) {
98
+ if (children.get(id) !== 1) anchors.add(id);
99
+ }
100
+ for (const id of anchors) removed.delete(id);
101
+ /** @type {Map<string,string|null>} */
102
+ const nearest = new Map();
103
+ for (const [id, parent] of parents) {
104
+ // Source-order ancestry makes this a linear pass, including long chains.
105
+ const ancestor = parent === null ? null : (nearest.get(parent) ?? null);
106
+ nearest.set(id, removed.has(id) ? ancestor : id);
107
+ parents.set(id, ancestor);
108
+ }
109
+ return { removed, parents, header };
110
+ }
111
+
112
+ /** @param {SessionEntry} entry @returns {string[]} */
113
+ function references(entry) {
114
+ if (entry.type === "compaction") return [entry.firstKeptEntryId];
115
+ if (entry.type === "branch_summary") return [entry.fromId];
116
+ if (entry.type === "label" || entry.type === "context_edit")
117
+ return [entry.targetId];
118
+ if (entry.type === "custom" && entry.customType === TREE_ARCHIVE_ENTRY_TYPE) {
119
+ if (!isTreeArchiveManifestData(entry.data))
120
+ throw new Error(
121
+ "Invalid Tree archive metadata; session history was not removed.",
122
+ );
123
+ const data = entry.data;
124
+ return [
125
+ data.boundaryEntryId,
126
+ data.summaryEntryId,
127
+ data.archivedLeafId,
128
+ ...(data.branchBaseId ? [data.branchBaseId] : []),
129
+ ...(data.compactionEntryId ? [data.compactionEntryId] : []),
130
+ ];
131
+ }
132
+ return [];
133
+ }