@howaboua/pi-notes-compaction 0.0.8 → 0.0.10

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 (53) hide show
  1. package/CHANGELOG.md +31 -5
  2. package/PCC-INTEGRATION.md +7 -98
  3. package/README.md +22 -14
  4. package/package.json +7 -3
  5. package/src/activation.ts +152 -0
  6. package/src/agent-identity.ts +119 -0
  7. package/src/attachment-snapshot.ts +103 -0
  8. package/src/binding-startup.ts +30 -0
  9. package/src/bridge.ts +1 -43
  10. package/src/compaction-projection.ts +88 -0
  11. package/src/context-owner.ts +103 -0
  12. package/src/context-sharing.ts +144 -0
  13. package/src/extension-hooks.ts +198 -0
  14. package/src/extension-sharing.ts +118 -0
  15. package/src/fresh-checkpoint.ts +117 -0
  16. package/src/fresh-notes.ts +141 -26
  17. package/src/history-search-protocol.ts +39 -0
  18. package/src/history-search-pruning.mjs +120 -0
  19. package/src/history-search-worker.mjs +256 -0
  20. package/src/history-search.ts +269 -0
  21. package/src/history.ts +219 -48
  22. package/src/idle-admission.ts +201 -0
  23. package/src/index.ts +71 -401
  24. package/src/integrations.ts +159 -0
  25. package/src/lifecycle.ts +63 -448
  26. package/src/note-save-marker.ts +112 -0
  27. package/src/notes-lookup.ts +112 -0
  28. package/src/notes.ts +25 -30
  29. package/src/query-executor.ts +190 -0
  30. package/src/remote.ts +357 -0
  31. package/src/rollover.ts +212 -0
  32. package/src/saved-session.ts +44 -7
  33. package/src/session-pruning-content.ts +237 -0
  34. package/src/session-pruning-plan.ts +243 -0
  35. package/src/session-pruning-policy.ts +20 -0
  36. package/src/session-pruning-screen.ts +130 -0
  37. package/src/session-pruning-source.ts +44 -0
  38. package/src/session-pruning-transaction.ts +141 -0
  39. package/src/session-pruning.ts +142 -0
  40. package/src/settings-command.ts +77 -0
  41. package/src/settings-screen.ts +89 -20
  42. package/src/settings.ts +152 -15
  43. package/src/shared-notes.ts +37 -14
  44. package/src/sharing-service.ts +348 -0
  45. package/src/store.ts +31 -0
  46. package/src/task-boundary.ts +6 -1
  47. package/src/tool-contracts.ts +279 -0
  48. package/src/tools.ts +19 -556
  49. package/src/tree-archive.ts +149 -0
  50. package/src/tree-checkpoint.ts +170 -0
  51. package/src/tree-handoff-read.ts +192 -0
  52. package/src/window-checkpoint.ts +105 -0
  53. package/src/windows.ts +28 -8
package/src/tools.ts CHANGED
@@ -1,4 +1,3 @@
1
- import { StringEnum } from "@earendil-works/pi-ai";
2
1
  import type {
3
2
  AgentToolResult,
4
3
  ExtensionAPI,
@@ -6,528 +5,27 @@ import type {
6
5
  ToolDefinition,
7
6
  } from "@earendil-works/pi-coding-agent";
8
7
  import { Type } from "typebox";
9
- import { Check } from "typebox/value";
10
- import type {
11
- CachedResponse,
12
- LookupQuery,
13
- SerializedCachedResponse,
14
- SharedNotesDetails,
15
- } from "./bridge.js";
16
- import { queryKey } from "./bridge.js";
17
- import { useHistory } from "./history.js";
8
+ import type { LookupQuery, SharedNotesDetails } from "./bridge.js";
9
+ import type { HistorySearch } from "./history-search.js";
18
10
  import type { NotesLifecycle } from "./lifecycle.js";
19
- import {
20
- CACHE_RECEIPT,
21
- collectNotes,
22
- normalizeNoteParams,
23
- sessionRef,
24
- sourceSessionIds,
25
- useNotes,
26
- } from "./notes.js";
27
- import {
28
- readSharedHistory,
29
- readSharedNotes,
30
- sharedNotesUnavailable,
31
- } from "./shared-notes.js";
11
+ import { createQueryExecutor } from "./query-executor.js";
32
12
  import type { NotesStore } from "./store.js";
33
-
34
- const NOTES_ACTIONS = [
35
- "help",
36
- "list_files_by_prefix",
37
- "read_file",
38
- "search_contents",
39
- "append_to_file",
40
- "write_file",
41
- ] as const;
42
- const HISTORY_ACTIONS = [
43
- "help",
44
- "list_windows",
45
- "list_items",
46
- "read_item",
47
- "search_contents",
48
- ] as const;
49
- export const NOTES_USAGE = "await tools.notes()";
50
- export const HISTORY_USAGE = "await tools.history()";
51
- const STRING = Type.Optional(Type.String());
52
- const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
53
- const NULLABLE_STRING = Type.Optional(Type.Union([Type.String(), Type.Null()]));
54
- const LINE = Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
55
- const NOTES_SCHEMA = Type.Object(
56
- {
57
- action: Type.Optional(StringEnum(NOTES_ACTIONS)),
58
- path: STRING,
59
- text: STRING,
60
- prefix: NULLABLE_STRING,
61
- query: STRING,
62
- path_prefix: NULLABLE_STRING,
63
- start_line: LINE,
64
- stop_line: LINE,
65
- max_results: INTEGER,
66
- max_files: INTEGER,
67
- max_matches_per_file: INTEGER,
68
- file_order: Type.Optional(StringEnum(["ascending", "descending"])),
69
- file_order_by: Type.Optional(
70
- StringEnum(["name", "created_at", "updated_at"]),
71
- ),
72
- recent_file_first: Type.Optional(Type.Boolean()),
73
- },
74
- { additionalProperties: false },
75
- );
76
- const HISTORY_SCHEMA = Type.Object(
77
- {
78
- action: Type.Optional(StringEnum(HISTORY_ACTIONS)),
79
- agent_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
80
- item_id: STRING,
81
- window_id: Type.Optional(Type.Union([Type.String(), Type.Null()])),
82
- query: STRING,
83
- limit: INTEGER,
84
- limit_chars: INTEGER,
85
- max_chars_per_item: INTEGER,
86
- offset_chars: Type.Optional(Type.Integer({ minimum: 0 })),
87
- recent_first: Type.Optional(Type.Boolean()),
88
- role: Type.Optional(
89
- Type.Union([
90
- StringEnum(["user", "assistant", "tool", "system", "developer"]),
91
- Type.Null(),
92
- ]),
93
- ),
94
- tool_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
95
- tool_namespace: Type.Optional(Type.Union([Type.String(), Type.Null()])),
96
- },
97
- { additionalProperties: false },
98
- );
99
-
100
- const FIELDS: Record<string, readonly string[]> = {
101
- list_files_by_prefix: [
102
- "prefix",
103
- "file_order",
104
- "file_order_by",
105
- "max_results",
106
- ],
107
- read_file: ["path", "start_line", "stop_line"],
108
- search_notes: [
109
- "query",
110
- "path_prefix",
111
- "max_files",
112
- "max_matches_per_file",
113
- "recent_file_first",
114
- ],
115
- append_to_file: ["path", "text"],
116
- write_file: ["path", "text"],
117
- list_windows: ["agent_name", "limit", "recent_first"],
118
- list_items: [
119
- "agent_name",
120
- "window_id",
121
- "role",
122
- "tool_name",
123
- "tool_namespace",
124
- "limit",
125
- "max_chars_per_item",
126
- "recent_first",
127
- ],
128
- read_item: [
129
- "agent_name",
130
- "window_id",
131
- "item_id",
132
- "offset_chars",
133
- "limit_chars",
134
- ],
135
- search_history: [
136
- "agent_name",
137
- "window_id",
138
- "role",
139
- "tool_name",
140
- "tool_namespace",
141
- "query",
142
- "limit",
143
- "recent_first",
144
- ],
145
- };
146
- function relevant(
147
- namespace: LookupQuery["namespace"],
148
- input: unknown,
149
- ): Record<string, unknown> {
150
- if (!input || typeof input !== "object" || Array.isArray(input))
151
- throw new Error("Supply an action object");
152
- const params = input as Record<string, unknown>;
153
- const action = params["action"];
154
- const key =
155
- action === "search_contents" ? `search_${namespace}` : String(action);
156
- const fields = FIELDS[key];
157
- if (!fields)
158
- throw new Error(
159
- namespace === "notes"
160
- ? "notes requires a supported action"
161
- : "Unknown action",
162
- );
163
- if (namespace === "notes") {
164
- for (const field of Object.keys(params))
165
- if (field !== "action" && !fields.includes(field))
166
- throw new Error(`notes ${String(action)} does not accept ${field}`);
167
- if (
168
- ["read_file", "write_file", "append_to_file"].includes(String(action)) &&
169
- (typeof params["path"] !== "string" || !params["path"])
170
- )
171
- throw new Error(`notes ${String(action)} requires path`);
172
- if (
173
- action === "search_contents" &&
174
- (typeof params["query"] !== "string" || !params["query"])
175
- )
176
- throw new Error("notes search_contents requires query");
177
- if (
178
- ["write_file", "append_to_file"].includes(String(action)) &&
179
- typeof params["text"] !== "string"
180
- )
181
- throw new Error(`notes ${String(action)} requires text`);
182
- }
183
- return Object.fromEntries(
184
- Object.entries(params).filter(
185
- ([key]) => key === "action" || fields.includes(key),
186
- ),
187
- );
188
- }
189
-
190
- function result(payload: unknown): AgentToolResult<unknown> {
191
- return {
192
- content: [{ type: "text", text: JSON.stringify(payload) }],
193
- details: {},
194
- };
195
- }
196
-
197
- function discovery(
198
- namespace: LookupQuery["namespace"],
199
- input: unknown,
200
- ): AgentToolResult<unknown> | undefined {
201
- const params = input === undefined ? {} : input;
202
- if (!params || typeof params !== "object" || Array.isArray(params))
203
- throw new Error("Supply an action object, or omit arguments for help");
204
- const entries = Object.entries(params);
205
- if (
206
- !entries.length ||
207
- (params as Record<string, unknown>)["action"] === "help"
208
- ) {
209
- if (entries.some(([key]) => key !== "action"))
210
- throw new Error("Help accepts only action: help");
211
- const actions = namespace === "notes" ? NOTES_ACTIONS : HISTORY_ACTIONS;
212
- return result({
213
- actions: Object.fromEntries(
214
- actions.map((action) => [
215
- action,
216
- action === "help"
217
- ? ""
218
- : FIELDS[
219
- action === "search_contents" ? `search_${namespace}` : action
220
- ]!.map((field) =>
221
- ["path", "text", "query", "item_id"].includes(field) ||
222
- (action === "read_item" && field === "window_id")
223
- ? field
224
- : `${field}?`,
225
- ).join(" "),
226
- ]),
227
- ),
228
- ...(namespace === "notes"
229
- ? {
230
- writes: "write_file replaces; append_to_file adds",
231
- paths:
232
- "Relative uses current agent; cross-agent uses <agent>/notes[/path]",
233
- usage: '{ "action": "read_file", "path": "checkpoint" }',
234
- ranges:
235
- "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",
236
- defaults:
237
- "list max_results 20; search max_files/max_matches_per_file 20; limits clamp to 1..100; list name ascending; search name ascending, recent_file_first sorts created_at descending",
238
- }
239
- : {
240
- usage:
241
- "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
242
- }),
243
- });
244
- }
245
- return undefined;
246
- }
247
-
248
- async function hybrid(
249
- pi: ExtensionAPI,
250
- store: NotesStore,
251
- lifecycle: NotesLifecycle,
252
- query: LookupQuery,
253
- local: Record<string, unknown>,
254
- callId: string,
255
- ctx: ExtensionContext,
256
- signal?: AbortSignal,
257
- shared = false,
258
- ): Promise<AgentToolResult<unknown>> {
259
- let responses: readonly CachedResponse[] = store.cached(
260
- sourceSessionIds(ctx),
261
- query,
262
- );
263
- let state = responses.length ? "cache" : "unavailable";
264
- let lookupFailed = false;
265
- const bridge = lifecycle.bridge;
266
- if (bridge?.lookup) {
267
- let fetched: readonly CachedResponse[] | undefined;
268
- try {
269
- fetched = await bridge.lookup(query, ctx, signal);
270
- } catch (error) {
271
- if (signal?.aborted) throw error;
272
- lookupFailed = true;
273
- }
274
- if (signal?.aborted) throw new Error("Lookup cancelled");
275
- if (fetched) {
276
- try {
277
- store.cache(sessionRef(ctx), fetched);
278
- } catch {
279
- throw new Error(
280
- "Remote results could not be retained locally. Retry this lookup when local storage is available.",
281
- );
282
- }
283
- if (fetched.length)
284
- pi.appendEntry(CACHE_RECEIPT, {
285
- protocol: 1,
286
- sessionId: ctx.sessionManager.getSessionId(),
287
- });
288
- const exact = fetched.filter(
289
- (response) => queryKey(response.query) === queryKey(query),
290
- );
291
- if (exact.length) {
292
- responses = exact;
293
- state = "live";
294
- }
295
- }
296
- }
297
- const canProject =
298
- shared ||
299
- (Boolean(bridge?.projectResult) && bridge?.canProject?.(ctx) !== false);
300
- if (responses.length && !canProject) state = "incompatible";
301
- const remote = {
302
- state,
303
- ...(lookupFailed
304
- ? {
305
- lookup: "failed",
306
- recovery: "Retry this lookup when remote access is available",
307
- }
308
- : {}),
309
- coverage: responses.length
310
- ? responses.map((response) => ({
311
- source: response.source,
312
- fetched_at: response.fetchedAt,
313
- coverage: response.coverage,
314
- }))
315
- : "No cached response for this exact query",
316
- ...(state === "cache"
317
- ? { scope: "Exact cached query only, not a complete offline archive" }
318
- : {}),
319
- ...(state === "incompatible"
320
- ? {
321
- recovery:
322
- "Cached encrypted contents are unavailable on this model. Local notes remain available",
323
- }
324
- : {}),
325
- };
326
- const output = result({ source: "local", local, remote });
327
- if (shared)
328
- return {
329
- ...output,
330
- details: {
331
- codexHistoryNotes: {},
332
- externalNotesResponses: responses.map(
333
- ({ bytes, ...response }): SerializedCachedResponse => ({
334
- ...response,
335
- bytesBase64: Buffer.from(bytes).toString("base64"),
336
- }),
337
- ),
338
- },
339
- };
340
- if (responses.length && canProject && bridge?.projectResult) {
341
- try {
342
- return await bridge.projectResult(output, responses, callId, ctx, signal);
343
- } catch {
344
- throw new Error(
345
- "Remote contents were cached, but delivery failed. Retry this lookup on a compatible model.",
346
- );
347
- }
348
- }
349
- return output;
350
- }
351
-
352
- function createQueryExecutor(
353
- pi: ExtensionAPI,
354
- store: NotesStore,
355
- lifecycle: NotesLifecycle,
356
- shared = false,
357
- ) {
358
- const assertActive = () => {
359
- if (!lifecycle.active)
360
- throw new Error(
361
- "Notes tools are inactive. Ask the user to check /notes.",
362
- );
363
- };
364
- async function notes(
365
- callId: string,
366
- input: unknown,
367
- signal: AbortSignal | undefined,
368
- ctx: ExtensionContext,
369
- ): Promise<AgentToolResult<unknown>> {
370
- const help = discovery("notes", input);
371
- if (help) return help;
372
- assertActive();
373
- const raw = relevant("notes", input);
374
- if (!shared) {
375
- try {
376
- const routed = await lifecycle.bridge?.route?.(
377
- { namespace: "notes", params: raw },
378
- callId,
379
- ctx,
380
- signal,
381
- );
382
- if (routed) return routed;
383
- } catch (error) {
384
- signal?.throwIfAborted();
385
- if (!sharedNotesUnavailable(error)) throw error;
386
- const saved = await readSharedNotes(ctx, store, raw, signal);
387
- if (saved) return result(saved);
388
- throw error;
389
- }
390
- const saved = await readSharedNotes(ctx, store, raw, signal);
391
- if (saved) return result(saved);
392
- }
393
- const params = relevant(
394
- "notes",
395
- normalizeNoteParams(raw, lifecycle.agent(ctx)),
396
- );
397
- if (signal?.aborted) throw new Error("Note operation cancelled");
398
- const local = useNotes(
399
- pi,
400
- store,
401
- params,
402
- ctx,
403
- lifecycle.agent(ctx),
404
- lifecycle.windows.current?.currentWindowId ?? "",
405
- lifecycle.runId,
406
- shared,
407
- );
408
- if (
409
- params["action"] === "write_file" ||
410
- params["action"] === "append_to_file"
411
- )
412
- return {
413
- ...result(local),
414
- details: {
415
- ...(shared
416
- ? { codexHistoryNotes: {}, notesCompactionRouted: true }
417
- : {
418
- notesCompaction: {
419
- protocol: 1,
420
- saved: true,
421
- runId: lifecycle.runId,
422
- },
423
- }),
424
- },
425
- };
426
- const notes = collectNotes(store, ctx.sessionManager.getBranch());
427
- if (
428
- params["action"] === "read_file" &&
429
- notes.get(params["path"] as string)?.mode === "replace"
430
- )
431
- return result({
432
- source: "local",
433
- local,
434
- remote: { state: "superseded_by_local_replacement" },
435
- });
436
- const replacements = [...notes.values()]
437
- .filter((note) => note.mode === "replace")
438
- .map((note) => `${lifecycle.agent(ctx)}/notes/${note.path}`);
439
- const remoteParams = { ...params };
440
- for (const field of ["path", "prefix", "path_prefix"])
441
- if (typeof remoteParams[field] === "string")
442
- remoteParams[field] =
443
- `${lifecycle.agent(ctx)}/notes${remoteParams[field] ? `/${remoteParams[field]}` : ""}`;
444
- return hybrid(
445
- pi,
446
- store,
447
- lifecycle,
448
- { namespace: "notes", params: remoteParams },
449
- {
450
- ...local,
451
- ...(replacements.length
452
- ? {
453
- local_replacements_authoritative: replacements.slice(0, 100),
454
- replacements_truncated: replacements.length > 100,
455
- }
456
- : {}),
457
- },
458
- callId,
459
- ctx,
460
- signal,
461
- shared,
462
- );
463
- }
464
- async function history(
465
- callId: string,
466
- input: unknown,
467
- signal: AbortSignal | undefined,
468
- ctx: ExtensionContext,
469
- ): Promise<AgentToolResult<unknown>> {
470
- const help = discovery("history", input);
471
- if (help) return help;
472
- assertActive();
473
- const params = relevant("history", input);
474
- const query = { namespace: "history", params } as const;
475
- if (!shared) {
476
- try {
477
- const routed = await lifecycle.bridge?.route?.(
478
- query,
479
- callId,
480
- ctx,
481
- signal,
482
- );
483
- if (routed) return routed;
484
- } catch (error) {
485
- signal?.throwIfAborted();
486
- if (
487
- !sharedNotesUnavailable(error) &&
488
- !(
489
- error instanceof Error &&
490
- error.message ===
491
- "Counterpart history requires its live attached owner; native history is unchanged"
492
- )
493
- )
494
- throw error;
495
- const saved = await readSharedHistory(ctx, store, params, signal);
496
- if (saved) return result(saved);
497
- throw error;
498
- }
499
- const saved = await readSharedHistory(ctx, store, params, signal);
500
- if (saved) return result(saved);
501
- }
502
- if (params["agent_name"] && params["agent_name"] !== lifecycle.agent(ctx))
503
- throw new Error(
504
- "That agent's history is not available here. Omit agent_name to search this session.",
505
- );
506
- return hybrid(
507
- pi,
508
- store,
509
- lifecycle,
510
- query,
511
- useHistory(
512
- ctx.sessionManager.getBranch(),
513
- params,
514
- ctx.sessionManager.getSessionId(),
515
- ),
516
- callId,
517
- ctx,
518
- signal,
519
- shared,
520
- );
521
- }
522
- return { notes, history };
523
- }
13
+ import {
14
+ HISTORY_SCHEMA,
15
+ NEW_CONTEXT_DESCRIPTION,
16
+ NOTES_DESCRIPTION,
17
+ NOTES_SCHEMA,
18
+ prepareNotesArguments,
19
+ result,
20
+ } from "./tool-contracts.js";
524
21
 
525
22
  export function createSharedExecutor(
526
23
  pi: ExtensionAPI,
527
24
  store: NotesStore,
528
25
  lifecycle: NotesLifecycle,
26
+ search: HistorySearch,
529
27
  ) {
530
- const queries = createQueryExecutor(pi, store, lifecycle, true);
28
+ const queries = createQueryExecutor(pi, store, lifecycle, search, true);
531
29
  return async (
532
30
  query: LookupQuery,
533
31
  callId: string,
@@ -551,6 +49,7 @@ export function createTools(
551
49
  pi: ExtensionAPI,
552
50
  store: NotesStore,
553
51
  lifecycle: NotesLifecycle,
52
+ search: HistorySearch,
554
53
  ): ToolDefinition[] {
555
54
  const assertActive = () => {
556
55
  if (!lifecycle.active)
@@ -558,50 +57,15 @@ export function createTools(
558
57
  "Notes tools are inactive. Ask the user to check /notes.",
559
58
  );
560
59
  };
561
- const queries = createQueryExecutor(pi, store, lifecycle);
60
+ const queries = createQueryExecutor(pi, store, lifecycle, search);
562
61
  return [
563
62
  {
564
63
  name: "notes",
565
64
  label: "notes",
566
- description: "Persistent notes",
65
+ description: NOTES_DESCRIPTION,
567
66
  parameters: NOTES_SCHEMA,
568
67
  executionMode: "sequential",
569
- prepareArguments(args) {
570
- if (args === undefined) return {};
571
- if (!args || typeof args !== "object" || Array.isArray(args))
572
- throw new Error(
573
- 'Supply an action object, e.g. { "action": "read_file", "path": "checkpoint" }. Use {} for help',
574
- );
575
- const params = { ...args } as Record<string, unknown>;
576
- if (
577
- (params["action"] === "write_file" ||
578
- params["action"] === "append_to_file") &&
579
- "content" in params
580
- ) {
581
- if (!("text" in params)) params["text"] = params["content"];
582
- delete params["content"];
583
- }
584
- if (
585
- params["action"] === "list_files_by_prefix" &&
586
- params["max_files"] !== undefined
587
- ) {
588
- if (!("max_results" in params))
589
- params["max_results"] = params["max_files"];
590
- delete params["max_files"];
591
- }
592
- if (!discovery("notes", params)) relevant("notes", params);
593
- for (const [field, value] of Object.entries(params)) {
594
- const schema =
595
- NOTES_SCHEMA.properties[
596
- field as keyof typeof NOTES_SCHEMA.properties
597
- ];
598
- if (!schema || !Check(schema, value))
599
- throw new Error(
600
- `Invalid notes ${field}; use {} for exact arguments`,
601
- );
602
- }
603
- return params;
604
- },
68
+ prepareArguments: prepareNotesArguments,
605
69
  execute: (callId, input, signal, _update, ctx) =>
606
70
  queries.notes(callId, input, signal, ctx),
607
71
  },
@@ -619,8 +83,7 @@ export function createTools(
619
83
  {
620
84
  name: "new_context",
621
85
  label: "new_context",
622
- description:
623
- "Start fresh from saved notes; recover earlier conversation through history",
86
+ description: NEW_CONTEXT_DESCRIPTION,
624
87
  parameters: Type.Object({}, { additionalProperties: false }),
625
88
  exposure: "model-only",
626
89
  executionMode: "sequential",
@@ -651,7 +114,7 @@ export function createTools(
651
114
  assertActive();
652
115
  const remaining = lifecycle.windows.remaining(ctx);
653
116
  return result({
654
- ...remaining,
117
+ contextWindow: remaining.contextWindow,
655
118
  remainingTokens: remaining.remainingTokens ?? null,
656
119
  remainingPercent: remaining.remainingPercent ?? null,
657
120
  });