@howaboua/pi-notes-compaction 0.0.5 → 0.0.7

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,421 @@
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";
7
+ import { Check } from "typebox/value";
8
+ import { useHistory } from "./history.js";
9
+ import { collectNotes, normalizeNoteParams, readNotes } from "./notes.js";
10
+ import {
11
+ readSavedNotesSession,
12
+ type SavedNotesSession,
13
+ } from "./saved-session.js";
14
+ import type { NotesStore } from "./store.js";
15
+
16
+ const Agent = Type.String({ pattern: "^/root(?:/[a-zA-Z0-9_-]+)*$" });
17
+ const Identity = Type.Object({
18
+ protocol: Type.Literal(1),
19
+ sessionId: Type.String(),
20
+ threadId: Type.String(),
21
+ agentName: Agent,
22
+ storage: Type.Optional(
23
+ Type.Union([Type.Literal("session"), Type.Literal("remote")]),
24
+ ),
25
+ routing: Type.Optional(Type.Unknown()),
26
+ });
27
+ const Member = Type.Object({
28
+ threadId: Type.String(),
29
+ sessionId: Type.String(),
30
+ agentName: Agent,
31
+ machine: Type.String(),
32
+ sessionFile: Type.String(),
33
+ });
34
+ const Plan = Type.Object({
35
+ controllerSessionId: Type.String(),
36
+ targetSessionId: Type.String(),
37
+ context: Type.Optional(
38
+ Type.Object({
39
+ controller: Identity,
40
+ target: Identity,
41
+ alias: Agent,
42
+ controllerAlias: Agent,
43
+ controllerFile: Type.Optional(Type.String()),
44
+ controllerNotes: Type.Unknown(),
45
+ targetNotes: Type.Unknown(),
46
+ }),
47
+ ),
48
+ });
49
+ const Route = Type.Object({
50
+ plan: Plan,
51
+ machine: Type.String(),
52
+ sessionFile: Type.String(),
53
+ phase: Type.Union([Type.Literal("pending"), Type.Literal("ready")]),
54
+ detached: Type.Optional(
55
+ Type.Object({ context: Type.Optional(Type.Unknown()) }),
56
+ ),
57
+ });
58
+ const Detachment = Type.Object({
59
+ plan: Plan,
60
+ context: Type.Optional(Type.Unknown()),
61
+ });
62
+ const Snapshot = Type.Object({
63
+ protocol: Type.Literal(1),
64
+ timestamp: Type.Number(),
65
+ files: Type.Array(
66
+ Type.Object({
67
+ path: Type.String(),
68
+ text: Type.String(),
69
+ createdAt: Type.Number(),
70
+ updatedAt: Type.Number(),
71
+ operation: Type.Union([
72
+ Type.Literal("local_append_overlay"),
73
+ Type.Literal("local_replacement"),
74
+ ]),
75
+ }),
76
+ ),
77
+ });
78
+ const Parent = Type.Object({
79
+ transport: Type.Literal("shepherdr"),
80
+ parent: Type.String(),
81
+ });
82
+ type Identity = Static<typeof Identity>;
83
+
84
+ function records(session: SavedNotesSession, kind: string): unknown[] {
85
+ return session.entries.flatMap((entry) =>
86
+ entry.type === "custom" && entry.customType === kind ? [entry.data] : [],
87
+ );
88
+ }
89
+
90
+ /** Persisted sharing is session-scoped. Forks never inherit the source agent's address. */
91
+ export function savedNotesIdentity(
92
+ session: Pick<SavedNotesSession, "threadId" | "entries">,
93
+ ): Identity {
94
+ let found: Identity | undefined;
95
+ for (const entry of session.entries) {
96
+ if (entry.type !== "custom" || entry.customType !== "codex-context-agent")
97
+ continue;
98
+ if (!Check(Identity, entry.data))
99
+ throw new Error("Invalid saved notes identity");
100
+ if (entry.data.threadId !== session.threadId) continue;
101
+ if (found) throw new Error("Conflicting saved notes identities");
102
+ found = entry.data;
103
+ }
104
+ return (
105
+ found ?? {
106
+ protocol: 1,
107
+ threadId: session.threadId,
108
+ sessionId: session.threadId,
109
+ agentName: "/root",
110
+ }
111
+ );
112
+ }
113
+
114
+ function sameOwner(a: Identity, b: Identity): boolean {
115
+ return (
116
+ a.threadId === b.threadId &&
117
+ a.sessionId === b.sessionId &&
118
+ a.agentName === b.agentName
119
+ );
120
+ }
121
+ function inside(path: string, root: string): boolean {
122
+ return path === root || path.startsWith(`${root}/`);
123
+ }
124
+ function remap(
125
+ params: Record<string, unknown>,
126
+ from: string,
127
+ to: string,
128
+ ): Record<string, unknown> {
129
+ return Object.fromEntries(
130
+ Object.entries(params).map(([key, value]) => [
131
+ key,
132
+ ["path", "prefix", "path_prefix"].includes(key) &&
133
+ typeof value === "string" &&
134
+ inside(value, from)
135
+ ? `${to}${value.slice(from.length)}`
136
+ : value,
137
+ ]),
138
+ );
139
+ }
140
+
141
+ export function sharedNotesUnavailable(error: unknown): boolean {
142
+ return (
143
+ error instanceof Error &&
144
+ /^(Cross-agent (?:context requires an available context router|notes (?:are unavailable here|owner is unavailable))|Shared context (?:owner|controller) is unavailable|Shared context response was lost|Herdr machine .* is (?:unavailable|disconnected)|remote Shepherdr bridge (?:is unavailable|closed|exited\b)|remote Shepherdr context timed out)/.test(
145
+ error.message,
146
+ )
147
+ );
148
+ }
149
+
150
+ /** Saved local notes do not need PCC, a router, or a running owner. Writes still belong to the live session. */
151
+ export async function readSharedNotes(
152
+ ctx: ExtensionContext,
153
+ store: Pick<NotesStore, "read">,
154
+ params: Record<string, unknown>,
155
+ signal?: AbortSignal,
156
+ ): Promise<Record<string, unknown> | undefined> {
157
+ return readSharedSession(ctx, store, params, "notes", signal);
158
+ }
159
+
160
+ export async function readSharedHistory(
161
+ ctx: ExtensionContext,
162
+ store: Pick<NotesStore, "read">,
163
+ params: Record<string, unknown>,
164
+ signal?: AbortSignal,
165
+ ): Promise<Record<string, unknown> | undefined> {
166
+ return readSharedSession(ctx, store, params, "history", signal);
167
+ }
168
+
169
+ async function readSharedSession(
170
+ ctx: ExtensionContext,
171
+ store: Pick<NotesStore, "read">,
172
+ params: Record<string, unknown>,
173
+ namespace: "notes" | "history",
174
+ signal?: AbortSignal,
175
+ ): Promise<Record<string, unknown> | undefined> {
176
+ if (
177
+ namespace === "notes" &&
178
+ !["read_file", "list_files_by_prefix", "search_contents"].includes(
179
+ String(params["action"]),
180
+ )
181
+ )
182
+ return;
183
+ const path =
184
+ namespace === "history"
185
+ ? params["agent_name"]
186
+ : (params["path"] ?? params["prefix"] ?? params["path_prefix"]);
187
+ if (typeof path !== "string" || !path.startsWith("/")) return;
188
+ const target =
189
+ namespace === "history"
190
+ ? /^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(path)
191
+ ? path
192
+ : undefined
193
+ : /^(\/root(?:\/[a-zA-Z0-9_-]+)*?)\/notes(?:\/|$)/.exec(path)?.[1];
194
+ if (!target) return;
195
+ const outputAgent = target;
196
+ const current: SavedNotesSession = {
197
+ threadId: ctx.sessionManager.getSessionId(),
198
+ entries: ctx.sessionManager.getEntries(),
199
+ branch: ctx.sessionManager.getBranch(),
200
+ };
201
+ if (savedNotesIdentity(current).agentName === target) return;
202
+ const visited = new Set<string>();
203
+
204
+ function read(
205
+ session: SavedNotesSession,
206
+ query: Record<string, unknown>,
207
+ native: string,
208
+ ) {
209
+ return {
210
+ ...(namespace === "history"
211
+ ? useHistory(session.branch, query, session.threadId)
212
+ : readNotes(
213
+ collectNotes(store, session.branch),
214
+ normalizeNoteParams(query, native),
215
+ outputAgent,
216
+ )),
217
+ source: "saved-session",
218
+ read_only: true,
219
+ remote: { state: "not_fetched" },
220
+ ...(session.savedAt === undefined
221
+ ? {}
222
+ : { saved_at: new Date(session.savedAt).toISOString() }),
223
+ };
224
+ }
225
+ async function reference(
226
+ identity: Identity,
227
+ destination: string,
228
+ query: Record<string, unknown>,
229
+ file: string | undefined,
230
+ retained?: unknown,
231
+ detached = false,
232
+ ): Promise<Record<string, unknown> | undefined> {
233
+ if (file && (!detached || namespace === "history")) {
234
+ let saved: SavedNotesSession | undefined;
235
+ try {
236
+ saved = await readSavedNotesSession(
237
+ file,
238
+ signal,
239
+ namespace === "history",
240
+ );
241
+ } catch (error) {
242
+ signal?.throwIfAborted();
243
+ if (
244
+ !(
245
+ error instanceof Error &&
246
+ "code" in error &&
247
+ error.code === "ENOENT" &&
248
+ retained !== undefined &&
249
+ namespace === "notes"
250
+ )
251
+ )
252
+ throw error;
253
+ }
254
+ if (saved) {
255
+ if (!sameOwner(savedNotesIdentity(saved), identity))
256
+ throw new Error("Saved shared notes belong to a different session");
257
+ return resolve(saved, destination, query);
258
+ }
259
+ }
260
+ if (
261
+ namespace === "history" ||
262
+ destination !== identity.agentName ||
263
+ !Check(Snapshot, retained)
264
+ )
265
+ return;
266
+ const entry: SessionEntry = {
267
+ type: "custom",
268
+ id: "retained",
269
+ parentId: null,
270
+ timestamp: new Date(retained.timestamp).toISOString(),
271
+ customType: "codex-context-note-snapshot",
272
+ data: {
273
+ ...retained,
274
+ files: retained.files.filter((file) =>
275
+ file.path.startsWith(`${identity.agentName}/notes/`),
276
+ ),
277
+ },
278
+ };
279
+ return {
280
+ ...read(
281
+ { threadId: identity.threadId, entries: [], branch: [entry] },
282
+ query,
283
+ identity.agentName,
284
+ ),
285
+ source: "retained-checkpoints",
286
+ captured_at: new Date(retained.timestamp).toISOString(),
287
+ ...(detached ? { detached: true } : { stale: true }),
288
+ };
289
+ }
290
+ async function resolve(
291
+ session: SavedNotesSession,
292
+ destination: string,
293
+ query: Record<string, unknown>,
294
+ ): Promise<Record<string, unknown> | undefined> {
295
+ signal?.throwIfAborted();
296
+ if (visited.has(session.threadId)) return;
297
+ visited.add(session.threadId);
298
+ const identity = savedNotesIdentity(session);
299
+ if (identity.agentName === destination) {
300
+ if (
301
+ namespace === "notes" &&
302
+ identity.storage === "remote" &&
303
+ !session.branch.some(
304
+ (entry) =>
305
+ entry.type === "custom" &&
306
+ entry.customType === "notes-compaction:note:v1",
307
+ )
308
+ )
309
+ return;
310
+ return read(session, query, identity.agentName);
311
+ }
312
+ const routes = new Map<string, Static<typeof Route>>();
313
+ for (const value of records(session, "shepherdr-attachment-route"))
314
+ if (
315
+ Check(Route, value) &&
316
+ value.plan.controllerSessionId === identity.threadId
317
+ )
318
+ routes.set(`${value.machine}\0${value.sessionFile}`, value);
319
+ for (const route of routes.values()) {
320
+ const link = route.plan.context;
321
+ if (route.phase !== "ready" || !link || !inside(destination, link.alias))
322
+ continue;
323
+ if (!sameOwner(identity, link.controller))
324
+ throw new Error("Saved shared notes identity changed");
325
+ return reference(
326
+ link.target,
327
+ `${link.target.agentName}${destination.slice(link.alias.length)}`,
328
+ remap(query, link.alias, link.target.agentName),
329
+ route.machine === "local" ? route.sessionFile : undefined,
330
+ route.detached?.context ?? link.targetNotes,
331
+ route.detached?.context !== undefined,
332
+ );
333
+ }
334
+ const owner = records(session, "shepherdr-attachment-owner").findLast(
335
+ (value) =>
336
+ Check(Plan, value) && value.targetSessionId === identity.threadId,
337
+ );
338
+ if (
339
+ Check(Plan, owner) &&
340
+ owner.context &&
341
+ inside(destination, owner.context.controllerAlias)
342
+ ) {
343
+ const link = owner.context;
344
+ if (!sameOwner(identity, link.target))
345
+ throw new Error("Saved shared notes identity changed");
346
+ const detached = records(
347
+ session,
348
+ "shepherdr-attachment-detached",
349
+ ).findLast(
350
+ (value) =>
351
+ Check(Detachment, value) && isDeepStrictEqual(value.plan, owner),
352
+ );
353
+ const snapshot = Check(Detachment, detached)
354
+ ? detached.context
355
+ : undefined;
356
+ return reference(
357
+ link.controller,
358
+ `${link.controller.agentName}${destination.slice(link.controllerAlias.length)}`,
359
+ remap(query, link.controllerAlias, link.controller.agentName),
360
+ link.controllerFile,
361
+ snapshot ?? link.controllerNotes,
362
+ snapshot !== undefined,
363
+ );
364
+ }
365
+ const member = records(session, "herdr-context-child").findLast(
366
+ (value) =>
367
+ Check(Member, value) &&
368
+ value.threadId === identity.threadId &&
369
+ value.sessionId === identity.sessionId &&
370
+ inside(destination, value.agentName),
371
+ );
372
+ if (Check(Member, member)) {
373
+ if (member.machine !== "local") return;
374
+ const saved = await readSavedNotesSession(
375
+ member.sessionFile,
376
+ signal,
377
+ namespace === "history",
378
+ );
379
+ const child = savedNotesIdentity(saved);
380
+ if (
381
+ child.sessionId !== identity.sessionId ||
382
+ child.agentName !== member.agentName
383
+ )
384
+ throw new Error(
385
+ "Saved shared notes belong to a different agent family",
386
+ );
387
+ return resolve(saved, destination, query);
388
+ }
389
+ const routing = identity.routing;
390
+ const suffix = ".jsonl.shepherdr-context.json";
391
+ if (Check(Parent, routing) && routing.parent.endsWith(suffix)) {
392
+ const saved = await readSavedNotesSession(
393
+ routing.parent.slice(0, -".shepherdr-context.json".length),
394
+ signal,
395
+ namespace === "history",
396
+ );
397
+ const parent = savedNotesIdentity(saved);
398
+ if (
399
+ parent.sessionId !== identity.sessionId ||
400
+ !identity.agentName.startsWith(`${parent.agentName}/`)
401
+ )
402
+ throw new Error("Saved shared notes parent identity changed");
403
+ return resolve(saved, destination, query);
404
+ }
405
+ return undefined;
406
+ }
407
+ try {
408
+ return await resolve(current, target, params);
409
+ } catch (error) {
410
+ if (
411
+ error instanceof Error &&
412
+ "code" in error &&
413
+ ["ENOENT", "EACCES", "EPERM"].includes(String(error.code))
414
+ )
415
+ throw new Error(
416
+ "Saved shared notes are unavailable on this machine. Restore access to the saved session, then retry.",
417
+ { cause: error },
418
+ );
419
+ throw error;
420
+ }
421
+ }
@@ -1,7 +1,7 @@
1
1
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
2
 
3
3
  export function renderTaskBoundaryReminder(remainingPercent: number): string {
4
- return `<context_window_reminder>\nThis window is approaching the recommended token budget. You still have ${remainingPercent}% of your context window remaining, so there is no need to start a new window immediately. If you are working through a sequence of tasks toward a larger goal, finish the current task, save a checkpoint, and start a new window before continuing with the next task. Otherwise, continue here.\n</context_window_reminder>`;
4
+ return `<context_window_reminder>\nSuggested context budget reached; ${remainingPercent}% remains. For a sequence of tasks, finish the current task, save notes and call new_context before the next. Otherwise, continue here.\n</context_window_reminder>`;
5
5
  }
6
6
 
7
7
  export const TASK_BOUNDARY_PRESETS = [
package/src/tools.ts CHANGED
@@ -24,6 +24,11 @@ import {
24
24
  sourceSessionIds,
25
25
  useNotes,
26
26
  } from "./notes.js";
27
+ import {
28
+ readSharedHistory,
29
+ readSharedNotes,
30
+ sharedNotesUnavailable,
31
+ } from "./shared-notes.js";
27
32
  import type { NotesStore } from "./store.js";
28
33
 
29
34
  const NOTES_ACTIONS = [
@@ -223,8 +228,7 @@ function discovery(
223
228
  ),
224
229
  ...(namespace === "notes"
225
230
  ? {
226
- usage:
227
- 'await tools.notes({ action: "read_file", path: "checkpoint" })',
231
+ usage: '{ "action": "read_file", "path": "checkpoint" }',
228
232
  ranges:
229
233
  "start_line/stop_line inclusive, 1-based; negative counts from end; 0/null/omitted uses first/last line; out-of-range clamps; reversed range returns empty content",
230
234
  defaults:
@@ -348,7 +352,9 @@ function createQueryExecutor(
348
352
  ) {
349
353
  const assertActive = () => {
350
354
  if (!lifecycle.active)
351
- throw new Error("Notes continuity is unavailable in this session");
355
+ throw new Error(
356
+ "Notes tools are inactive. Ask the user to check /notes.",
357
+ );
352
358
  };
353
359
  async function notes(
354
360
  callId: string,
@@ -360,15 +366,25 @@ function createQueryExecutor(
360
366
  if (help) return help;
361
367
  assertActive();
362
368
  const raw = relevant("notes", input);
363
- const routed =
364
- !shared &&
365
- (await lifecycle.bridge?.route?.(
366
- { namespace: "notes", params: raw },
367
- callId,
368
- ctx,
369
- signal,
370
- ));
371
- if (routed) return routed;
369
+ if (!shared) {
370
+ try {
371
+ const routed = await lifecycle.bridge?.route?.(
372
+ { namespace: "notes", params: raw },
373
+ callId,
374
+ ctx,
375
+ signal,
376
+ );
377
+ if (routed) return routed;
378
+ } catch (error) {
379
+ signal?.throwIfAborted();
380
+ if (!sharedNotesUnavailable(error)) throw error;
381
+ const saved = await readSharedNotes(ctx, store, raw, signal);
382
+ if (saved) return result(saved);
383
+ throw error;
384
+ }
385
+ const saved = await readSharedNotes(ctx, store, raw, signal);
386
+ if (saved) return result(saved);
387
+ }
372
388
  const params = relevant(
373
389
  "notes",
374
390
  normalizeNoteParams(raw, lifecycle.agent(ctx)),
@@ -451,9 +467,33 @@ function createQueryExecutor(
451
467
  assertActive();
452
468
  const params = relevant("history", input);
453
469
  const query = { namespace: "history", params } as const;
454
- const routed =
455
- !shared && (await lifecycle.bridge?.route?.(query, callId, ctx, signal));
456
- if (routed) return routed;
470
+ if (!shared) {
471
+ try {
472
+ const routed = await lifecycle.bridge?.route?.(
473
+ query,
474
+ callId,
475
+ ctx,
476
+ signal,
477
+ );
478
+ if (routed) return routed;
479
+ } catch (error) {
480
+ signal?.throwIfAborted();
481
+ if (
482
+ !sharedNotesUnavailable(error) &&
483
+ !(
484
+ error instanceof Error &&
485
+ error.message ===
486
+ "Counterpart history requires its live attached owner; native history is unchanged"
487
+ )
488
+ )
489
+ throw error;
490
+ const saved = await readSharedHistory(ctx, store, params, signal);
491
+ if (saved) return result(saved);
492
+ throw error;
493
+ }
494
+ const saved = await readSharedHistory(ctx, store, params, signal);
495
+ if (saved) return result(saved);
496
+ }
457
497
  if (params["agent_name"] && params["agent_name"] !== lifecycle.agent(ctx))
458
498
  throw new Error(
459
499
  "That agent's history is not available here. Omit agent_name to search this session.",
@@ -509,7 +549,9 @@ export function createTools(
509
549
  ): ToolDefinition[] {
510
550
  const assertActive = () => {
511
551
  if (!lifecycle.active)
512
- throw new Error("Notes continuity is unavailable in this session");
552
+ throw new Error(
553
+ "Notes tools are inactive. Ask the user to check /notes.",
554
+ );
513
555
  };
514
556
  const queries = createQueryExecutor(pi, store, lifecycle);
515
557
  return [
@@ -517,14 +559,14 @@ export function createTools(
517
559
  name: "notes",
518
560
  label: "notes",
519
561
  description:
520
- "Cross-window notes. write_file replaces; append_to_file adds. Virtual paths: relative uses current agent; cross-agent uses <agent>/notes[/path].",
562
+ "Persistent notes. write_file replaces; append_to_file adds. Virtual paths: relative uses current agent; cross-agent uses <agent>/notes[/path].",
521
563
  parameters: NOTES_SCHEMA,
522
564
  executionMode: "sequential",
523
565
  prepareArguments(args) {
524
566
  if (args === undefined) return {};
525
567
  if (!args || typeof args !== "object" || Array.isArray(args))
526
568
  throw new Error(
527
- 'Supply an action object: await tools.notes({ action: "read_file", path: "checkpoint" }); tools.notes() returns help',
569
+ 'Supply an action object, e.g. { "action": "read_file", "path": "checkpoint" }. Use {} for help',
528
570
  );
529
571
  const params = { ...args } as Record<string, unknown>;
530
572
  if (
@@ -551,7 +593,7 @@ export function createTools(
551
593
  ];
552
594
  if (!schema || !Check(schema, value))
553
595
  throw new Error(
554
- `Invalid notes ${field}; call tools.notes() for exact arguments`,
596
+ `Invalid notes ${field}; use {} for exact arguments`,
555
597
  );
556
598
  }
557
599
  return params;
@@ -563,7 +605,7 @@ export function createTools(
563
605
  name: "history",
564
606
  label: "history",
565
607
  description:
566
- "Prior-window detail. Pass IDs unchanged. Search, never browse",
608
+ "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
567
609
  parameters: HISTORY_SCHEMA,
568
610
  prepareArguments(args) {
569
611
  return args === undefined ? {} : args;
@@ -574,22 +616,23 @@ export function createTools(
574
616
  {
575
617
  name: "new_context",
576
618
  label: "new_context",
577
- description: "Start a new context window",
619
+ description:
620
+ "Start fresh from saved notes; recover earlier conversation through history",
578
621
  parameters: Type.Object({}, { additionalProperties: false }),
579
622
  exposure: "model-only",
580
623
  executionMode: "sequential",
581
- async execute(_id, _input, signal, _update, ctx) {
624
+ async execute(id, _input, signal, _update, ctx) {
582
625
  assertActive();
583
626
  if (signal?.aborted) throw new Error("Rollover cancelled");
584
- const started = lifecycle.requestRollover(ctx);
627
+ const started = lifecycle.requestRollover(ctx, id);
585
628
  if (started) ctx.abort();
586
629
  return {
587
630
  ...result({
588
631
  started,
589
632
  message: started
590
- ? lifecycle.normalCompaction
591
- ? "Normal compaction will run before the new window opens"
592
- : "A new window will continue from your notes after this run settles"
633
+ ? lifecycle.newWindowRequests === "pi-limits"
634
+ ? "Window request queued. Pi will check whether enough history can be compacted"
635
+ : "A new window will open after this run settles"
593
636
  : "A checkpoint or rollover is already pending. Save notes and finish your response",
594
637
  }),
595
638
  ...(started ? { terminate: true } : {}),