@howaboua/pi-notes-compaction 0.0.10 → 0.0.12

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.
@@ -1,86 +1,25 @@
1
1
  import { isDeepStrictEqual } from "node:util";
2
- import type {
3
- ExtensionContext,
4
- SessionEntry,
5
- } from "@earendil-works/pi-coding-agent";
6
- import { type Static, Type } from "typebox";
2
+ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
3
+ import type { Static } from "typebox";
7
4
  import { Check } from "typebox/value";
8
- import { useHistory } from "./history.js";
9
5
  import type { HistorySearch } from "./history-search.js";
10
- import { collectNotes, normalizeNoteParams, readNotes } from "./notes.js";
11
6
  import {
12
7
  readSavedNotesSession,
13
8
  type SavedNotesSession,
14
9
  } from "./saved-session.js";
10
+ import {
11
+ Detachment,
12
+ Member,
13
+ Parent,
14
+ Plan,
15
+ Route,
16
+ sameOwner,
17
+ savedNotesIdentity,
18
+ } from "./saved-sharing-records.js";
19
+ import { createSharedSessionReader } from "./shared-session-reader.js";
15
20
  import type { NotesStore } from "./store.js";
16
21
 
17
- const Agent = Type.String({ pattern: "^/root(?:/[a-zA-Z0-9_-]+)*$" });
18
- const Identity = Type.Object({
19
- protocol: Type.Literal(1),
20
- sessionId: Type.String(),
21
- threadId: Type.String(),
22
- agentName: Agent,
23
- storage: Type.Optional(
24
- Type.Union([Type.Literal("session"), Type.Literal("remote")]),
25
- ),
26
- routing: Type.Optional(Type.Unknown()),
27
- });
28
- const Member = Type.Object({
29
- threadId: Type.String(),
30
- sessionId: Type.String(),
31
- agentName: Agent,
32
- machine: Type.String(),
33
- sessionFile: Type.String(),
34
- });
35
- const Plan = Type.Object({
36
- controllerSessionId: Type.String(),
37
- targetSessionId: Type.String(),
38
- context: Type.Optional(
39
- Type.Object({
40
- controller: Identity,
41
- target: Identity,
42
- alias: Agent,
43
- controllerAlias: Agent,
44
- controllerFile: Type.Optional(Type.String()),
45
- controllerNotes: Type.Unknown(),
46
- targetNotes: Type.Unknown(),
47
- }),
48
- ),
49
- });
50
- const Route = Type.Object({
51
- plan: Plan,
52
- machine: Type.String(),
53
- sessionFile: Type.String(),
54
- phase: Type.Union([Type.Literal("pending"), Type.Literal("ready")]),
55
- detached: Type.Optional(
56
- Type.Object({ context: Type.Optional(Type.Unknown()) }),
57
- ),
58
- });
59
- const Detachment = Type.Object({
60
- plan: Plan,
61
- context: Type.Optional(Type.Unknown()),
62
- });
63
- const Snapshot = Type.Object({
64
- protocol: Type.Literal(1),
65
- timestamp: Type.Number(),
66
- files: Type.Array(
67
- Type.Object({
68
- path: Type.String(),
69
- text: Type.String(),
70
- createdAt: Type.Number(),
71
- updatedAt: Type.Number(),
72
- operation: Type.Union([
73
- Type.Literal("local_append_overlay"),
74
- Type.Literal("local_replacement"),
75
- ]),
76
- }),
77
- ),
78
- });
79
- const Parent = Type.Object({
80
- transport: Type.Literal("shepherdr"),
81
- parent: Type.String(),
82
- });
83
- type Identity = Static<typeof Identity>;
22
+ export { savedNotesIdentity } from "./saved-sharing-records.js";
84
23
 
85
24
  function records(session: SavedNotesSession, kind: string): unknown[] {
86
25
  return session.entries.flatMap((entry) =>
@@ -88,37 +27,6 @@ function records(session: SavedNotesSession, kind: string): unknown[] {
88
27
  );
89
28
  }
90
29
 
91
- /** Persisted sharing is session-scoped. Forks never inherit the source agent's address. */
92
- export function savedNotesIdentity(
93
- session: Pick<SavedNotesSession, "threadId" | "entries">,
94
- ): Identity {
95
- let found: Identity | undefined;
96
- for (const entry of session.entries) {
97
- if (entry.type !== "custom" || entry.customType !== "codex-context-agent")
98
- continue;
99
- if (!Check(Identity, entry.data))
100
- throw new Error("Invalid saved notes identity");
101
- if (entry.data.threadId !== session.threadId) continue;
102
- if (found) throw new Error("Conflicting saved notes identities");
103
- found = entry.data;
104
- }
105
- return (
106
- found ?? {
107
- protocol: 1,
108
- threadId: session.threadId,
109
- sessionId: session.threadId,
110
- agentName: "/root",
111
- }
112
- );
113
- }
114
-
115
- function sameOwner(a: Identity, b: Identity): boolean {
116
- return (
117
- a.threadId === b.threadId &&
118
- a.sessionId === b.sessionId &&
119
- a.agentName === b.agentName
120
- );
121
- }
122
30
  function inside(path: string, root: string): boolean {
123
31
  return path === root || path.startsWith(`${root}/`);
124
32
  }
@@ -212,104 +120,13 @@ async function readSharedSession(
212
120
  if (savedNotesIdentity(current).agentName === target) return;
213
121
  const visited = new Set<string>();
214
122
 
215
- async function read(
216
- session: SavedNotesSession,
217
- query: Record<string, unknown>,
218
- native: string,
219
- ) {
220
- return {
221
- ...(access.namespace === "history"
222
- ? await useHistory(
223
- session.branch,
224
- query,
225
- session.threadId,
226
- access.search,
227
- session.entries,
228
- signal,
229
- )
230
- : readNotes(
231
- collectNotes(store, session.branch),
232
- normalizeNoteParams(query, native),
233
- outputAgent,
234
- )),
235
- ...(namespace === "notes"
236
- ? {
237
- read_only: true,
238
- warning:
239
- "Only saved notes are included; other notes may be missing",
240
- }
241
- : {}),
242
- ...(session.savedAt === undefined
243
- ? {}
244
- : { saved_at: new Date(session.savedAt).toISOString() }),
245
- };
246
- }
247
- async function reference(
248
- identity: Identity,
249
- destination: string,
250
- query: Record<string, unknown>,
251
- file: string | undefined,
252
- retained?: unknown,
253
- detached = false,
254
- ): Promise<Record<string, unknown> | undefined> {
255
- if (file && (!detached || namespace === "history")) {
256
- let saved: SavedNotesSession | undefined;
257
- try {
258
- saved = await readSavedNotesSession(
259
- file,
260
- signal,
261
- namespace === "history",
262
- );
263
- } catch (error) {
264
- signal?.throwIfAborted();
265
- if (
266
- !(
267
- error instanceof Error &&
268
- "code" in error &&
269
- error.code === "ENOENT" &&
270
- retained !== undefined &&
271
- namespace === "notes"
272
- )
273
- )
274
- throw error;
275
- }
276
- if (saved) {
277
- if (!sameOwner(savedNotesIdentity(saved), identity))
278
- throw new Error("Saved shared notes belong to a different session");
279
- return resolve(saved, destination, query);
280
- }
281
- }
282
- if (
283
- namespace === "history" ||
284
- destination !== identity.agentName ||
285
- !Check(Snapshot, retained)
286
- )
287
- return;
288
- const entry: SessionEntry = {
289
- type: "custom",
290
- id: "retained",
291
- parentId: null,
292
- timestamp: new Date(retained.timestamp).toISOString(),
293
- customType: "codex-context-note-snapshot",
294
- data: {
295
- ...retained,
296
- files: retained.files.filter((file) =>
297
- file.path.startsWith(`${identity.agentName}/notes/`),
298
- ),
299
- },
300
- };
301
- return {
302
- ...(await read(
303
- { threadId: identity.threadId, entries: [], branch: [entry] },
304
- query,
305
- identity.agentName,
306
- )),
307
- captured_at: new Date(retained.timestamp).toISOString(),
308
- warning: detached
309
- ? "Read-only notes captured when sharing ended; later changes are not included"
310
- : "The latest notes are unavailable; this read-only copy may be outdated",
311
- };
312
- }
123
+ const { read, reference } = createSharedSessionReader(
124
+ store,
125
+ access,
126
+ outputAgent,
127
+ signal,
128
+ resolve,
129
+ );
313
130
  async function resolve(
314
131
  session: SavedNotesSession,
315
132
  destination: string,
@@ -0,0 +1,132 @@
1
+ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
2
+ import { Check } from "typebox/value";
3
+ import { useHistory } from "./history.js";
4
+ import type { HistorySearch } from "./history-search.js";
5
+ import { normalizeNoteParams, readNotes } from "./note-query.js";
6
+ import { collectNotes } from "./notes.js";
7
+ import {
8
+ readSavedNotesSession,
9
+ type SavedNotesSession,
10
+ } from "./saved-session.js";
11
+ import {
12
+ type Identity,
13
+ Snapshot,
14
+ sameOwner,
15
+ savedNotesIdentity,
16
+ } from "./saved-sharing-records.js";
17
+ import type { NotesStore } from "./store.js";
18
+
19
+ export function createSharedSessionReader(
20
+ store: Pick<NotesStore, "read">,
21
+ access:
22
+ | { namespace: "notes" }
23
+ | { namespace: "history"; search: HistorySearch },
24
+ outputAgent: string,
25
+ signal: AbortSignal | undefined,
26
+ resolve: (
27
+ session: SavedNotesSession,
28
+ destination: string,
29
+ query: Record<string, unknown>,
30
+ ) => Promise<Record<string, unknown> | undefined>,
31
+ ) {
32
+ const { namespace } = access;
33
+ async function read(
34
+ session: SavedNotesSession,
35
+ query: Record<string, unknown>,
36
+ native: string,
37
+ ) {
38
+ return {
39
+ ...(access.namespace === "history"
40
+ ? await useHistory(
41
+ session.branch,
42
+ query,
43
+ session.threadId,
44
+ access.search,
45
+ session.entries,
46
+ signal,
47
+ )
48
+ : readNotes(
49
+ collectNotes(store, session.branch),
50
+ normalizeNoteParams(query, native),
51
+ outputAgent,
52
+ )),
53
+ ...(namespace === "notes"
54
+ ? {
55
+ read_only: true,
56
+ warning:
57
+ "Only saved notes are included; other notes may be missing",
58
+ }
59
+ : {}),
60
+ ...(session.savedAt === undefined
61
+ ? {}
62
+ : { saved_at: new Date(session.savedAt).toISOString() }),
63
+ };
64
+ }
65
+ async function reference(
66
+ identity: Identity,
67
+ destination: string,
68
+ query: Record<string, unknown>,
69
+ file: string | undefined,
70
+ retained?: unknown,
71
+ detached = false,
72
+ ): Promise<Record<string, unknown> | undefined> {
73
+ if (file && (!detached || namespace === "history")) {
74
+ let saved: SavedNotesSession | undefined;
75
+ try {
76
+ saved = await readSavedNotesSession(
77
+ file,
78
+ signal,
79
+ namespace === "history",
80
+ );
81
+ } catch (error) {
82
+ signal?.throwIfAborted();
83
+ if (
84
+ !(
85
+ error instanceof Error &&
86
+ "code" in error &&
87
+ error.code === "ENOENT" &&
88
+ retained !== undefined &&
89
+ namespace === "notes"
90
+ )
91
+ )
92
+ throw error;
93
+ }
94
+ if (saved) {
95
+ if (!sameOwner(savedNotesIdentity(saved), identity))
96
+ throw new Error("Saved shared notes belong to a different session");
97
+ return resolve(saved, destination, query);
98
+ }
99
+ }
100
+ if (
101
+ namespace === "history" ||
102
+ destination !== identity.agentName ||
103
+ !Check(Snapshot, retained)
104
+ )
105
+ return;
106
+ const entry: SessionEntry = {
107
+ type: "custom",
108
+ id: "retained",
109
+ parentId: null,
110
+ timestamp: new Date(retained.timestamp).toISOString(),
111
+ customType: "codex-context-note-snapshot",
112
+ data: {
113
+ ...retained,
114
+ files: retained.files.filter((file) =>
115
+ file.path.startsWith(`${identity.agentName}/notes/`),
116
+ ),
117
+ },
118
+ };
119
+ return {
120
+ ...(await read(
121
+ { threadId: identity.threadId, entries: [], branch: [entry] },
122
+ query,
123
+ identity.agentName,
124
+ )),
125
+ captured_at: new Date(retained.timestamp).toISOString(),
126
+ warning: detached
127
+ ? "Read-only notes captured when sharing ended; later changes are not included"
128
+ : "The latest notes are unavailable; this read-only copy may be outdated",
129
+ };
130
+ }
131
+ return { read, reference };
132
+ }
@@ -3,7 +3,6 @@ import { isDeepStrictEqual } from "node:util";
3
3
  import type {
4
4
  ExtensionAPI,
5
5
  ExtensionContext,
6
- SessionEntry,
7
6
  } from "@earendil-works/pi-coding-agent";
8
7
  import {
9
8
  CONTEXT_AGENT_ENTRY,
@@ -11,10 +10,7 @@ import {
11
10
  contextTargetAgent,
12
11
  parseContextAgentBinding,
13
12
  } from "./agent-identity.js";
14
- import {
15
- readAttachmentSnapshot,
16
- readRemoteNoteReference,
17
- } from "./attachment-snapshot.js";
13
+ import { createAttachmentSharing } from "./attachment-sharing.js";
18
14
  import { bindingStartupEntries } from "./binding-startup.js";
19
15
  import type { NotesOwner } from "./bridge.js";
20
16
  import {
@@ -25,7 +21,6 @@ import {
25
21
  type SharedContextRequest,
26
22
  type SharedContextResult,
27
23
  } from "./context-sharing.js";
28
- import { exportNotesSnapshot } from "./notes.js";
29
24
 
30
25
  export function registerContextSharingService(
31
26
  pi: ExtensionAPI,
@@ -199,116 +194,7 @@ export function registerContextSharingService(
199
194
  );
200
195
  return config.execute(ctx, request, signal);
201
196
  },
202
- exportAttachmentNotes(ctx) {
203
- const identity = describe(ctx);
204
- if (!identity)
205
- throw new Error("Checkpoint export requires notes-based continuity");
206
- if (identity.storage === "remote") {
207
- if (!identity.backendUrl)
208
- throw new Error("Saved remote context has no backend address");
209
- return {
210
- protocol: 1,
211
- storage: "remote",
212
- timestamp: Date.now(),
213
- identity,
214
- baseUrl: identity.backendUrl,
215
- };
216
- }
217
-
218
- const snapshot = exportNotesSnapshot(
219
- ctx.sessionManager.getBranch(),
220
- identity.agentName,
221
- );
222
- return {
223
- ...snapshot,
224
- files: snapshot.files.filter(
225
- (file) =>
226
- contextTargetAgent(
227
- "notes",
228
- { path: file.path },
229
- identity.agentName,
230
- ) === identity.agentName,
231
- ),
232
- };
233
- },
234
- validateAttachmentNotes(snapshot, identity) {
235
- if (identity.storage === "remote") {
236
- if (
237
- !isDeepStrictEqual(
238
- readRemoteNoteReference(snapshot).identity,
239
- identity,
240
- )
241
- )
242
- throw new Error("Remote checkpoint owner changed");
243
- } else
244
- readAttachmentSnapshot(snapshot, {
245
- action: "list_files_by_prefix",
246
- prefix: `${identity.agentName}/notes`,
247
- });
248
- },
249
- async verifyAttachmentAccess(ctx, snapshot) {
250
- if (
251
- !snapshot ||
252
- typeof snapshot !== "object" ||
253
- !("storage" in snapshot) ||
254
- snapshot.storage !== "remote"
255
- )
256
- return;
257
- const { verifyRemoteReference } = await import("./remote.js");
258
- await verifyRemoteReference(ctx, readRemoteNoteReference(snapshot));
259
- },
260
- async executeRemoteAttachment(ctx, snapshot, request, signal) {
261
- if (request.namespace === "history")
262
- throw new Error(
263
- "History is unavailable from a saved remote notes attachment. Open its saved Pi JSONL session on this machine, then retry.",
264
- );
265
- const { executeRemoteAttachment } = await import("./remote.js");
266
- return executeRemoteAttachment(
267
- ctx,
268
- readRemoteNoteReference(snapshot),
269
- request,
270
- signal,
271
- );
272
- },
273
- parseAttachmentNotes(input, identity) {
274
- if (!Array.isArray(input))
275
- throw new Error("Invalid persisted checkpoint entries");
276
- const entries: SessionEntry[] = input.map((entry: unknown) => {
277
- if (
278
- !entry ||
279
- typeof entry !== "object" ||
280
- !("type" in entry) ||
281
- !(
282
- (entry.type === "custom" &&
283
- "customType" in entry &&
284
- typeof entry.customType === "string" &&
285
- "data" in entry) ||
286
- (entry.type === "branch_summary" && "details" in entry)
287
- )
288
- )
289
- throw new Error("Invalid persisted checkpoint entry");
290
- return entry as SessionEntry;
291
- });
292
- const snapshot = exportNotesSnapshot(entries, identity.agentName);
293
- return {
294
- ...snapshot,
295
- files: snapshot.files.filter(
296
- (file) =>
297
- contextTargetAgent(
298
- "notes",
299
- { path: file.path },
300
- identity.agentName,
301
- ) === identity.agentName,
302
- ),
303
- };
304
- },
305
- readAttachmentNotes(snapshot, params) {
306
- const details = readAttachmentSnapshot(snapshot, params);
307
- return {
308
- content: [{ type: "text", text: JSON.stringify(details) }],
309
- details: { codexHistoryNotes: details },
310
- };
311
- },
197
+ ...createAttachmentSharing(describe),
312
198
  registerRouter(next) {
313
199
  if (router && router !== next)
314
200
  throw new Error("A context router is already registered");
package/src/sqlite.mjs ADDED
@@ -0,0 +1,33 @@
1
+ import { createRequire } from "node:module";
2
+
3
+ // Only the shared SQLite surface used by Notes. Bun returns null for a missing
4
+ // row (better-sqlite3 returns undefined); blobs may be Uint8Array, not Buffer.
5
+ /** @template {unknown[]} P
6
+ * @template R
7
+ * @typedef {{get(...params:P): R | null | undefined; all(...params:P): R[]; run(...params:P): {changes:number; lastInsertRowid:number|bigint}}} Statement
8
+ */
9
+ /** @template {unknown[]} P
10
+ * @template R
11
+ * @typedef {((...params:P) => R) & {immediate(...params:P):R}} Transaction
12
+ */
13
+ /** @typedef {{
14
+ * prepare<P extends unknown[] = unknown[], R = unknown>(sql:string): Statement<P,R>;
15
+ * transaction<P extends unknown[], R>(fn:(...params:P) => R): Transaction<P,R>;
16
+ * exec(sql:string):void;
17
+ * close():void;
18
+ * }} Database
19
+ */
20
+
21
+ const require = createRequire(import.meta.url);
22
+
23
+ /** Avoid loading the native addon at all in Bun, including compiled Pi builds.
24
+ * @param {string} path
25
+ * @returns {Database}
26
+ */
27
+ export function openDatabase(path) {
28
+ /** @type {new(path:string) => Database} */
29
+ const Database = process.versions["bun"]
30
+ ? require("bun:sqlite").Database
31
+ : require("better-sqlite3");
32
+ return new Database(path);
33
+ }
package/src/store.ts CHANGED
@@ -1,7 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { existsSync, mkdirSync, statSync } from "node:fs";
3
3
  import { dirname } from "node:path";
4
- import Database from "better-sqlite3";
5
4
  import type { CachedResponse, LookupQuery } from "./bridge.js";
6
5
  import { queryKey } from "./bridge.js";
7
6
  import {
@@ -9,6 +8,7 @@ import {
9
8
  pruningPolicy,
10
9
  type SessionPruningPolicy,
11
10
  } from "./session-pruning-policy.js";
11
+ import { type Database, openDatabase } from "./sqlite.mjs";
12
12
 
13
13
  export interface SessionRef {
14
14
  id: string;
@@ -24,7 +24,7 @@ export interface NoteRevision {
24
24
  }
25
25
  interface CacheRow {
26
26
  query_json: string;
27
- bytes: Buffer;
27
+ bytes: Uint8Array;
28
28
  source: string;
29
29
  encoding: string;
30
30
  fetched_at: number;
@@ -33,21 +33,23 @@ interface CacheRow {
33
33
 
34
34
  /** One connection per extension process. Read-only access never creates a database or session. */
35
35
  export class NotesStore {
36
- private db: Database.Database | undefined;
36
+ private db: Database | undefined;
37
37
  readonly path: string;
38
38
  constructor(path: string) {
39
39
  this.path = path;
40
40
  }
41
- private open(write = false): Database.Database | undefined {
41
+ private open(write = false): Database | undefined {
42
42
  if (this.db) return this.db;
43
43
  if (!write && !existsSync(this.path)) return undefined;
44
44
  if (write) mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
45
- const db = new Database(this.path);
45
+ const db = openDatabase(this.path);
46
46
  try {
47
- db.pragma("busy_timeout = 5000");
48
- db.pragma("journal_mode = WAL");
49
- db.pragma("foreign_keys = ON");
50
- const version = db.pragma("user_version", { simple: true });
47
+ db.exec("PRAGMA busy_timeout = 5000");
48
+ db.exec("PRAGMA journal_mode = WAL");
49
+ db.exec("PRAGMA foreign_keys = ON");
50
+ const version = db
51
+ .prepare<[], { user_version: number }>("PRAGMA user_version")
52
+ .get()?.user_version;
51
53
  if (version !== 0 && version !== 1) {
52
54
  throw new Error("Notes database version is not supported");
53
55
  }
@@ -77,7 +79,7 @@ export class NotesStore {
77
79
  );
78
80
  }
79
81
  }
80
- private record(db: Database.Database, session: SessionRef): void {
82
+ private record(db: Database, session: SessionRef): void {
81
83
  db.prepare(
82
84
  "INSERT INTO sessions VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET file_path = COALESCE(excluded.file_path, sessions.file_path), updated_at = excluded.updated_at",
83
85
  ).run(session.id, session.file ?? null, Date.now());
@@ -118,11 +120,11 @@ export class NotesStore {
118
120
  }
119
121
  read(id: string): NoteRevision | undefined {
120
122
  const row = this.open()
121
- ?.prepare(
123
+ ?.prepare<[string], NoteRevision>(
122
124
  "SELECT id, path, text, mode, created_at AS createdAt, updated_at AS updatedAt FROM notes WHERE id = ?",
123
125
  )
124
- .get(id) as NoteRevision | undefined;
125
- return row;
126
+ .get(id);
127
+ return row ?? undefined;
126
128
  }
127
129
  updateFile(session: SessionRef): void {
128
130
  if (!session.file) return;