@howaboua/pi-notes-compaction 0.0.7 → 0.0.8

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # @howaboua/pi-notes-compaction
2
2
 
3
+ ## 0.0.8
4
+
5
+ - **Continuity and integrations**
6
+
7
+ - Fixed Notes guidance missing from PCC's first post-compaction cache-warming request.
8
+ - With PCC active, Notes guidance uses developer-role delivery. Automatic rollover resumes from the window handoff itself, without a separate continuation message.
9
+ - Initial window identity now follows the prepared system prompt, preserving the shared prefix for child-agent caching.
10
+ - External integrations can adopt a new fork into a notes family before its first task without rewriting inherited history.
11
+
12
+ **Guidance and discovery**
13
+
14
+ - Added compact checkpoint guidance for PCC GPT prompt mode.
15
+ - Simplified Notes and History discovery, with write, path and history-ID guidance in their help.
16
+ - Tightened notes guidance to favour concise milestone checkpoints over progress logs and repeated reads.
17
+
3
18
  ## 0.0.7
4
19
 
5
20
  - Shared local agent history now remains readable after its owner closes or Shepherdr is removed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-notes-compaction",
3
- "version": "0.0.7",
3
+ "version": "0.0.8",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -39,6 +39,7 @@
39
39
  "better-sqlite3": "13.0.3"
40
40
  },
41
41
  "devDependencies": {
42
+ "@howaboua/pi-codex-conversion": "4.0.2",
42
43
  "@types/better-sqlite3": "9.6.0"
43
44
  },
44
45
  "peerDependencies": {
@@ -46,6 +47,12 @@
46
47
  "@earendil-works/pi-agent-core": ">=1.0.4",
47
48
  "@earendil-works/pi-ai": ">=1.0.4",
48
49
  "@earendil-works/pi-tui": ">=1.0.4",
50
+ "@howaboua/pi-codex-conversion": ">=4.0.2",
49
51
  "typebox": "*"
52
+ },
53
+ "peerDependenciesMeta": {
54
+ "@howaboua/pi-codex-conversion": {
55
+ "optional": true
56
+ }
50
57
  }
51
58
  }
package/src/bridge.ts CHANGED
@@ -68,12 +68,16 @@ export interface NotesOwner {
68
68
  protocol: 1;
69
69
  owner: "pi-notes-compaction";
70
70
  identity(ctx: ExtensionContext): WindowIdentity | undefined;
71
- projectMessages(messages: readonly AgentMessage[]): AgentMessage[];
71
+ /** Current branch refreshes projection before later lifecycle hooks have run. */
72
+ projectMessages(
73
+ messages: readonly AgentMessage[],
74
+ entries?: readonly SessionEntry[],
75
+ ): AgentMessage[];
72
76
  projectBranch(entries: readonly SessionEntry[]): SessionEntry[];
73
77
  /** Consult before compaction work; the owner's hook performs notes-only rollover. */
74
78
  allowsCompaction?(reason: SessionBeforeCompactEvent["reason"]): boolean;
75
79
  allowsWindowRequests?(): boolean;
76
- canBind?(ctx: ExtensionContext): boolean;
80
+ canBind?(ctx: ExtensionContext, entries?: readonly SessionEntry[]): boolean;
77
81
  snapshotNotes?(
78
82
  entries: readonly SessionEntry[],
79
83
  agentName: string,
package/src/index.ts CHANGED
@@ -33,7 +33,7 @@ import {
33
33
  windowDetails,
34
34
  } from "./windows.js";
35
35
 
36
- export default function notesCompaction(pi: ExtensionAPI): void {
36
+ export default async function notesCompaction(pi: ExtensionAPI): Promise<void> {
37
37
  registerWindowRenderer(pi);
38
38
  const dir = join(getAgentDir(), "notes-compaction");
39
39
  const settingsPath = join(dir, "settings.json");
@@ -56,6 +56,27 @@ export default function notesCompaction(pi: ExtensionAPI): void {
56
56
  },
57
57
  );
58
58
  const tools = createTools(pi, store, lifecycle);
59
+ try {
60
+ const { registerGptPromptMode } = await import(
61
+ "@howaboua/pi-codex-conversion/prompt-mode"
62
+ );
63
+ const registration = registerGptPromptMode(pi, () =>
64
+ lifecycle.active ? tools : [],
65
+ );
66
+ lifecycle.gptPromptMode = () => registration.active;
67
+ } catch (error) {
68
+ if (
69
+ !(error instanceof Error) ||
70
+ !("code" in error) ||
71
+ ![
72
+ "ERR_MODULE_NOT_FOUND",
73
+ "MODULE_NOT_FOUND",
74
+ "ERR_PACKAGE_PATH_NOT_EXPORTED",
75
+ ].includes(String(error.code)) ||
76
+ !error.message.includes("@howaboua/pi-codex-conversion")
77
+ )
78
+ throw error;
79
+ }
59
80
  let ownSource: string | undefined;
60
81
  let unavailable: string | undefined;
61
82
  const owner: NotesOwner = {
@@ -63,7 +84,8 @@ export default function notesCompaction(pi: ExtensionAPI): void {
63
84
  owner: "pi-notes-compaction",
64
85
  identity: () =>
65
86
  lifecycle.windows.current ? { ...lifecycle.windows.current } : undefined,
66
- projectMessages: (messages) => {
87
+ projectMessages: (messages, entries) => {
88
+ if (entries) lifecycle.windows.restore(entries);
67
89
  const projected = lifecycle.windows.projectMessages(
68
90
  messages,
69
91
  lifecycle.bridge?.prepareReminder,
@@ -79,10 +101,10 @@ export default function notesCompaction(pi: ExtensionAPI): void {
79
101
  projectBranch: (entries) => lifecycle.windows.projectBranch(entries),
80
102
  allowsCompaction: (reason) => lifecycle.allowsCompaction(reason),
81
103
  allowsWindowRequests: () => lifecycle.newWindowRequests !== "off",
82
- canBind: (ctx) =>
104
+ canBind: (ctx, entries = ctx.sessionManager.getEntries()) =>
83
105
  lifecycle.active &&
84
106
  ctx.isIdle() &&
85
- ctx.sessionManager.getEntries().every((entry) => {
107
+ entries.every((entry) => {
86
108
  // The first startup after an update records a UI-only changelog.
87
109
  if (
88
110
  entry.type === "custom" &&
@@ -206,7 +228,6 @@ export default function notesCompaction(pi: ExtensionAPI): void {
206
228
  ?.sourceInfo.path;
207
229
  }
208
230
  lifecycle.active = true;
209
- lifecycle.initialize(ctx);
210
231
  configureTools(ctx);
211
232
  store.updateFile(sessionRef(ctx));
212
233
  } catch (error) {
@@ -279,7 +300,7 @@ export default function notesCompaction(pi: ExtensionAPI): void {
279
300
  });
280
301
  pi.on("before_agent_start", (event, ctx) => {
281
302
  refreshActivation(ctx);
282
- if (lifecycle.active) lifecycle.beforeStart(ctx, event);
303
+ if (lifecycle.active) return lifecycle.beforeStart(ctx, event);
283
304
  });
284
305
  pi.on("input", (event, ctx) => {
285
306
  refreshActivation(ctx);
@@ -316,17 +337,19 @@ export default function notesCompaction(pi: ExtensionAPI): void {
316
337
  ? {
317
338
  entries: [
318
339
  ...event.entries,
319
- windowDetails(reminder)?.kind === "task-boundary"
320
- ? (lifecycle.bridge?.prepareReminder?.(reminder) ?? reminder)
321
- : reminder,
340
+ lifecycle.bridge?.prepareReminder?.(reminder) ?? reminder,
322
341
  ],
323
342
  }
324
343
  : undefined;
325
344
  });
326
345
  pi.on("context", (event, ctx) => {
327
346
  try {
328
- lifecycle.windows.restore(ctx.sessionManager.getBranch());
329
- return { messages: owner.projectMessages(event.messages) };
347
+ return {
348
+ messages: owner.projectMessages(
349
+ event.messages,
350
+ ctx.sessionManager.getBranch(),
351
+ ),
352
+ };
330
353
  } catch (error) {
331
354
  ctx.abort();
332
355
  throw error;
@@ -344,7 +367,6 @@ export default function notesCompaction(pi: ExtensionAPI): void {
344
367
  });
345
368
  pi.on("session_tree", (_event, ctx) => {
346
369
  lifecycle.reset(ctx);
347
- if (lifecycle.active) lifecycle.initialize(ctx);
348
370
  });
349
371
  pi.on("model_select", (_event, ctx) => {
350
372
  refreshActivation(ctx);
package/src/lifecycle.ts CHANGED
@@ -2,6 +2,8 @@ import { randomUUID } from "node:crypto";
2
2
  import type {
3
3
  AgentSettledEvent,
4
4
  BeforeAgentStartEvent,
5
+ BeforeAgentStartEventResult,
6
+ CustomMessageEntryDraft,
5
7
  ExtensionAPI,
6
8
  ExtensionContext,
7
9
  InputEvent,
@@ -55,6 +57,7 @@ type Rollover = {
55
57
 
56
58
  export class NotesLifecycle {
57
59
  readonly windows = new Windows();
60
+ gptPromptMode = () => false;
58
61
  active = false;
59
62
  normalCompaction = false;
60
63
  newWindowRequests: NewWindowRequests = "unrestricted";
@@ -80,6 +83,20 @@ export class NotesLifecycle {
80
83
  this.pi = pi;
81
84
  this.store = store;
82
85
  }
86
+ private sendMessage(
87
+ message: Omit<CustomMessageEntryDraft, "type">,
88
+ options: { triggerTurn: boolean },
89
+ ): void {
90
+ const draft: CustomMessageEntryDraft = {
91
+ type: "custom_message",
92
+ ...message,
93
+ details: message.details ?? {},
94
+ };
95
+ this.pi.sendMessage(
96
+ this.bridge?.prepareReminder?.(draft) ?? draft,
97
+ options,
98
+ );
99
+ }
83
100
  agent(ctx: ExtensionContext): string {
84
101
  return (
85
102
  this.bridge?.agentName?.(ctx) ??
@@ -100,7 +117,9 @@ export class NotesLifecycle {
100
117
  this.runId = "";
101
118
  this.windows.restore(ctx?.sessionManager.getBranch() ?? []);
102
119
  }
103
- initialize(ctx: ExtensionContext): void {
120
+ private initialize(
121
+ ctx: ExtensionContext,
122
+ ): CustomMessageEntryDraft | undefined {
104
123
  const branch = ctx.sessionManager.getBranch();
105
124
  this.windows.restore(branch);
106
125
  const latest = branch.findLast(
@@ -112,36 +131,44 @@ export class NotesLifecycle {
112
131
  if (!this.windows.current || !latest) {
113
132
  const inherited = Boolean(this.windows.current);
114
133
  const ids = this.windows.current ?? this.windows.next();
115
- this.pi.sendMessage(
116
- windowMessage(
117
- ids,
118
- this.agent(ctx),
119
- noteHints(this.store, ctx, this.agent(ctx)),
120
- false,
121
- inherited ? "identity" : "window",
122
- ),
123
- { triggerTurn: false },
124
- );
125
134
  this.windows.current = ids;
135
+ return windowMessage(
136
+ ids,
137
+ this.agent(ctx),
138
+ noteHints(this.store, ctx, this.agent(ctx)),
139
+ false,
140
+ inherited ? "identity" : "window",
141
+ this.gptPromptMode(),
142
+ );
126
143
  } else if (
127
144
  latest.type === "custom_message" &&
128
145
  typeof latest.content === "string" &&
129
146
  !latest.content.includes(`Agent name: ${this.agent(ctx)}\n`)
130
147
  ) {
131
- this.pi.sendMessage(
132
- windowMessage(
133
- this.windows.current,
134
- this.agent(ctx),
135
- noteHints(this.store, ctx, this.agent(ctx)),
136
- false,
137
- "identity",
138
- ),
139
- { triggerTurn: false },
148
+ return windowMessage(
149
+ this.windows.current,
150
+ this.agent(ctx),
151
+ noteHints(this.store, ctx, this.agent(ctx)),
152
+ false,
153
+ "identity",
154
+ this.gptPromptMode(),
140
155
  );
141
156
  }
142
157
  }
143
- beforeStart(ctx: ExtensionContext, event: BeforeAgentStartEvent): void {
144
- this.initialize(ctx);
158
+ beforeStart(
159
+ ctx: ExtensionContext,
160
+ event: BeforeAgentStartEvent,
161
+ ): BeforeAgentStartEventResult | undefined {
162
+ // A custom kickoff is not in the branch until after before_agent_start.
163
+ // Adopt its boundary without restoring the outgoing window or emitting a duplicate.
164
+ const startingWindow =
165
+ event.messageType === "custom"
166
+ ? windowDetails({ ...event.message, type: "custom_message" })
167
+ : undefined;
168
+ let message: CustomMessageEntryDraft | undefined;
169
+ if (startingWindow?.kind === "window")
170
+ this.windows.current = startingWindow.identity;
171
+ else message = this.initialize(ctx);
145
172
  this.runId = randomUUID();
146
173
  this.pi.appendEntry(NOTES_RUN_ENTRY, { runId: this.runId });
147
174
  if (
@@ -152,6 +179,9 @@ export class NotesLifecycle {
152
179
  ?.requestId === this.checkpoint.requestId
153
180
  )
154
181
  this.checkpoint.runId = this.runId;
182
+ return message
183
+ ? { message: this.bridge?.prepareReminder?.(message) ?? message }
184
+ : undefined;
155
185
  }
156
186
  prepareCustomTurn(ctx: ExtensionContext): Promise<void> | undefined {
157
187
  if (this.customAdmission) return this.customAdmission;
@@ -218,19 +248,18 @@ export class NotesLifecycle {
218
248
  throw new Error("Session changed before rollover");
219
249
  const ids = this.windows.next();
220
250
  const hint = noteHints(this.store, ctx, this.agent(ctx));
221
- this.pi.sendMessage(windowMessage(ids, this.agent(ctx), hint, trim), {
222
- triggerTurn: false,
223
- });
251
+ const message = windowMessage(
252
+ ids,
253
+ this.agent(ctx),
254
+ hint,
255
+ trim,
256
+ "window",
257
+ this.gptPromptMode(),
258
+ );
224
259
  this.windows.current = ids;
225
260
  if (triggerTurn)
226
- this.pi.sendMessage(
227
- {
228
- customType: "notes-compaction:continuation",
229
- content: "Read your saved notes and resume the task.",
230
- display: false,
231
- },
232
- { triggerTurn: true },
233
- );
261
+ message.content = `${message.content}\n\nRead your saved notes and resume the task.`;
262
+ this.sendMessage(message, { triggerTurn });
234
263
  }
235
264
  private async roll(
236
265
  ctx: ExtensionContext,
@@ -291,7 +320,7 @@ export class NotesLifecycle {
291
320
  this.rollover = undefined;
292
321
  try {
293
322
  if (triggerTurn)
294
- this.pi.sendMessage(
323
+ this.sendMessage(
295
324
  {
296
325
  customType: "notes-compaction:continuation",
297
326
  content:
@@ -325,7 +354,7 @@ export class NotesLifecycle {
325
354
  outcome: undefined,
326
355
  };
327
356
  try {
328
- this.pi.sendMessage(
357
+ this.sendMessage(
329
358
  {
330
359
  customType: "notes-compaction:checkpoint:v1",
331
360
  details: { requestId },
package/src/tools.ts CHANGED
@@ -46,9 +46,8 @@ const HISTORY_ACTIONS = [
46
46
  "read_item",
47
47
  "search_contents",
48
48
  ] as const;
49
- export const NOTES_USAGE =
50
- "await tools.notes({ action, ...args }) // no args: help; actions(required args): list_files_by_prefix(); read_file(path); search_contents(query); append_to_file(path,text); write_file(path,text)";
51
- export const HISTORY_USAGE = "await tools.history() // help";
49
+ export const NOTES_USAGE = "await tools.notes()";
50
+ export const HISTORY_USAGE = "await tools.history()";
52
51
  const STRING = Type.Optional(Type.String());
53
52
  const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
54
53
  const NULLABLE_STRING = Type.Optional(Type.Union([Type.String(), Type.Null()]));
@@ -228,13 +227,19 @@ function discovery(
228
227
  ),
229
228
  ...(namespace === "notes"
230
229
  ? {
230
+ writes: "write_file replaces; append_to_file adds",
231
+ paths:
232
+ "Relative uses current agent; cross-agent uses <agent>/notes[/path]",
231
233
  usage: '{ "action": "read_file", "path": "checkpoint" }',
232
234
  ranges:
233
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",
234
236
  defaults:
235
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",
236
238
  }
237
- : {}),
239
+ : {
240
+ usage:
241
+ "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
242
+ }),
238
243
  });
239
244
  }
240
245
  return undefined;
@@ -558,8 +563,7 @@ export function createTools(
558
563
  {
559
564
  name: "notes",
560
565
  label: "notes",
561
- description:
562
- "Persistent notes. write_file replaces; append_to_file adds. Virtual paths: relative uses current agent; cross-agent uses <agent>/notes[/path].",
566
+ description: "Persistent notes",
563
567
  parameters: NOTES_SCHEMA,
564
568
  executionMode: "sequential",
565
569
  prepareArguments(args) {
@@ -604,8 +608,7 @@ export function createTools(
604
608
  {
605
609
  name: "history",
606
610
  label: "history",
607
- description:
608
- "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
611
+ description: "Search earlier conversation",
609
612
  parameters: HISTORY_SCHEMA,
610
613
  prepareArguments(args) {
611
614
  return args === undefined ? {} : args;
package/src/windows.ts CHANGED
@@ -24,9 +24,15 @@ export interface WindowDetails {
24
24
  trim: boolean;
25
25
  }
26
26
  const GUIDANCE = `<context_window_guidance>
27
- Notes persist across windows. Keep one checkpoint per task at a stable path, covering the request, constraints, decisions, progress, next steps and history IDs so you can resume without rereading the conversation. Replace stale state; mark completion in place. Keep reusable findings and deferred ideas in separate topic notes; link, don't copy. Recording isn't permission to implement.
27
+ Notes are recovery state, not a diary. Keep one concise, authoritative note per task or topic at a stable path. Task checkpoints cover request, constraints, decisions, status, next steps and history IDs. Use write_file to replace stale state and mark completion. Link to existing notes instead of copying or summarising their contents. Recording isn't permission to implement.
28
28
 
29
- Save changed state after substantial work, before replying, and before new_context or handoff. Skip routine or unchanged state. Include checkpoint paths in handoffs. After rollover, read the checkpoint, then linked notes as needed. History retrieves earlier conversation; use it only for missing details.
29
+ Batch saves at meaningful milestones, not every reply or intermediate step. Before new_context or handoff, save current state and wait for success; include the checkpoint path in handoffs. After rollover, read the checkpoint, then only needed links. Don't reread notes still in context unless they may have changed. Use history for missing details.
30
+ </context_window_guidance>`;
31
+
32
+ const GPT_GUIDANCE = `<context_window_guidance>
33
+ Notes=recovery state, not diary. One concise authoritative note/task or topic, stable path. Checkpoints: request, constraints, decisions, status, next steps, history IDs. write_file replaces stale state; mark completion. Link existing notes, don't copy/summarise. Recording != permission to implement.
34
+
35
+ Batch saves at meaningful milestones, not every reply/step. Before new_context/handoff: save current state, await success; handoff includes checkpoint path. After rollover: read checkpoint, then needed links only. Don't reread notes still in context unless possibly changed. history fills missing details.
30
36
  </context_window_guidance>`;
31
37
 
32
38
  export function registerWindowRenderer(pi: ExtensionAPI): void {
@@ -152,6 +158,7 @@ export function windowMessage(
152
158
  hint: string,
153
159
  trim: boolean,
154
160
  kind: "window" | "identity" = "window",
161
+ gpt = false,
155
162
  ): CustomMessageEntryDraft {
156
163
  const lines = [
157
164
  `Agent name: ${agent}`,
@@ -164,7 +171,7 @@ export function windowMessage(
164
171
  return {
165
172
  type: "custom_message",
166
173
  customType: WINDOW_MESSAGE,
167
- content: `${GUIDANCE}\n\n<context_window>\n${lines.join("\n")}\n</context_window>`,
174
+ content: `${gpt ? GPT_GUIDANCE : GUIDANCE}\n\n<context_window>\n${lines.join("\n")}\n</context_window>`,
168
175
  display: true,
169
176
  details: {
170
177
  protocol: 1,