@howaboua/pi-notes-compaction 0.0.7 → 0.0.9

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,28 @@
1
1
  # @howaboua/pi-notes-compaction
2
2
 
3
+ ## 0.0.9
4
+
5
+ - - Fixed history lookup errors to identify the missing ID and explain how to retry. History arguments now clarify that read_item requires both IDs.
6
+ - GPT-mode checkpoint guidance uses denser prose.
7
+ - New-window guidance tells agents to read task-relevant skills again.
8
+ - Notes write receipts now contain only the saved path.
9
+ - Idle rollover offers Off, 25m, 55m, 2h, 6h and 12h. Hour presets roll over five minutes early; saved 5- and 15-minute settings remain valid.
10
+
11
+ ## 0.0.8
12
+
13
+ - **Continuity and integrations**
14
+
15
+ - Fixed Notes guidance missing from PCC's first post-compaction cache-warming request.
16
+ - With PCC active, Notes guidance uses developer-role delivery. Automatic rollover resumes from the window handoff itself, without a separate continuation message.
17
+ - Initial window identity now follows the prepared system prompt, preserving the shared prefix for child-agent caching.
18
+ - External integrations can adopt a new fork into a notes family before its first task without rewriting inherited history.
19
+
20
+ **Guidance and discovery**
21
+
22
+ - Added compact checkpoint guidance for PCC GPT prompt mode.
23
+ - Simplified Notes and History discovery, with write, path and history-ID guidance in their help.
24
+ - Tightened notes guidance to favour concise milestone checkpoints over progress logs and repeated reads.
25
+
3
26
  ## 0.0.7
4
27
 
5
28
  - Shared local agent history now remains readable after its owner closes or Shepherdr is removed.
package/README.md CHANGED
@@ -28,7 +28,7 @@ Reminders arrive at 85% and 90% context use. With normal compaction off, `/compa
28
28
 
29
29
  Pi rejects `/compact` when there is too little history to prepare compaction, before extensions run. `new_context` follows the separate **New window requests** setting.
30
30
 
31
- Idle rollover is off by default. Choose 5, 15, 25 or 55 minutes in `/notes`. After that interval, the next input waits for rollover only if the latest completed turn saved fresh notes. Otherwise it proceeds in the current window without requesting a checkpoint. These intervals are user preferences, not provider cache-expiry guarantees. Held input retains its original text, attachments and SDK options. If normal compaction has nothing to summarise, input proceeds in the current window. A failed rollover keeps input pending. Submit another prompt to retry, or reload to cancel it.
31
+ Idle rollover is off by default. Choose 25m, 55m, 2h, 6h or 12h in `/notes`. Hour presets use a five-minute buffer, stored as 115, 355 or 715 minutes. Saved 5- and 15-minute settings remain valid. After the interval, the next input waits for rollover only if the latest completed turn saved fresh notes. Otherwise it proceeds in the current window without requesting a checkpoint. These intervals are user preferences, not provider cache-expiry guarantees. Held input retains its original text, attachments and SDK options. If normal compaction has nothing to summarise, input proceeds in the current window. A failed rollover keeps input pending. Submit another prompt to retry, or reload to cancel it.
32
32
 
33
33
  ## Management
34
34
 
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.9",
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.3",
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.3",
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/history.ts CHANGED
@@ -129,14 +129,13 @@ export function useHistory(
129
129
  };
130
130
  }
131
131
  if (action === "read_item") {
132
- if (
133
- typeof params["window_id"] !== "string" ||
134
- typeof params["item_id"] !== "string"
135
- )
136
- throw new Error("Supply window_id and item_id unchanged from history");
137
- const item = windows
138
- .get(params["window_id"])
139
- ?.find((item) => item.item_id === params["item_id"]);
132
+ const windowId = params["window_id"];
133
+ const itemId = params["item_id"];
134
+ if (typeof windowId !== "string" || typeof itemId !== "string")
135
+ throw new Error(
136
+ `history read_item requires ${typeof windowId !== "string" ? "window_id" : "item_id"} as a string. Copy window_id and item_id from the same search_contents or list_items result`,
137
+ );
138
+ const item = windows.get(windowId)?.find((item) => item.item_id === itemId);
140
139
  if (!item) return { item: null };
141
140
  const offset = integer(params["offset_chars"], 0, item.content.length);
142
141
  const limit = integer(params["limit_chars"], 8000, 8000);
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/notes.ts CHANGED
@@ -331,8 +331,7 @@ export function useNotes(
331
331
  );
332
332
  }
333
333
  return {
334
- source: "pi-session",
335
- file: noteMetadata(revision, root),
334
+ file: { path: `${root}${path}` },
336
335
  };
337
336
  }
338
337
  return readNotes(notes, params, agent);
@@ -29,7 +29,11 @@ export async function openNotesSettings(
29
29
  (tui, theme, _kb, done) => {
30
30
  const settings = options.settings();
31
31
  const idleValue = (minutes: number) =>
32
- minutes === 0 ? "off" : `${minutes} min`;
32
+ minutes === 0
33
+ ? "Off"
34
+ : minutes < 60
35
+ ? `${minutes}m`
36
+ : `${Math.ceil(minutes / 60)}h`;
33
37
  const list = new SettingsList(
34
38
  [
35
39
  {
package/src/settings.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
2
2
  import { dirname } from "node:path";
3
3
 
4
- export const IDLE_MINUTES = [0, 5, 15, 25, 55] as const;
5
- export type IdleMinutes = (typeof IDLE_MINUTES)[number];
4
+ // Hour presets store their effective duration, with five minutes of headroom.
5
+ export const IDLE_MINUTES = [0, 25, 55, 115, 355, 715] as const;
6
+ export type IdleMinutes = (typeof IDLE_MINUTES)[number] | 5 | 15;
6
7
  export const NEW_WINDOW_REQUESTS = [
7
8
  "off",
8
9
  "pi-limits",
@@ -85,9 +86,13 @@ export function readSettings(path: string): NotesSettings {
85
86
  throw new Error(
86
87
  "Invalid task-boundary reminder setting. Save a setting in /notes, then reload Pi.",
87
88
  );
88
- if (!IDLE_MINUTES.some((value) => value === idleMinutes))
89
+ if (
90
+ idleMinutes !== 5 &&
91
+ idleMinutes !== 15 &&
92
+ !IDLE_MINUTES.some((value) => value === idleMinutes)
93
+ )
89
94
  throw new Error(
90
- "Invalid idle rollover interval. Choose off, 5, 15, 25 or 55 minutes.",
95
+ "Invalid idle rollover interval. Set idleMinutes to 0, 25, 55, 115, 355 or 715, then reload Pi.",
91
96
  );
92
97
  return {
93
98
  active,
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()]));
@@ -79,7 +78,11 @@ const HISTORY_SCHEMA = Type.Object(
79
78
  action: Type.Optional(StringEnum(HISTORY_ACTIONS)),
80
79
  agent_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
81
80
  item_id: STRING,
82
- window_id: Type.Optional(Type.Union([Type.String(), Type.Null()])),
81
+ window_id: Type.Optional(
82
+ Type.Union([Type.String(), Type.Null()], {
83
+ description: "Required with item_id for read_item",
84
+ }),
85
+ ),
83
86
  query: STRING,
84
87
  limit: INTEGER,
85
88
  limit_chars: INTEGER,
@@ -228,13 +231,19 @@ function discovery(
228
231
  ),
229
232
  ...(namespace === "notes"
230
233
  ? {
234
+ writes: "write_file replaces; append_to_file adds",
235
+ paths:
236
+ "Relative uses current agent; cross-agent uses <agent>/notes[/path]",
231
237
  usage: '{ "action": "read_file", "path": "checkpoint" }',
232
238
  ranges:
233
239
  "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
240
  defaults:
235
241
  "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
242
  }
237
- : {}),
243
+ : {
244
+ usage:
245
+ "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
246
+ }),
238
247
  });
239
248
  }
240
249
  return undefined;
@@ -558,8 +567,7 @@ export function createTools(
558
567
  {
559
568
  name: "notes",
560
569
  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].",
570
+ description: "Persistent notes",
563
571
  parameters: NOTES_SCHEMA,
564
572
  executionMode: "sequential",
565
573
  prepareArguments(args) {
@@ -604,8 +612,7 @@ export function createTools(
604
612
  {
605
613
  name: "history",
606
614
  label: "history",
607
- description:
608
- "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
615
+ description: "Search earlier conversation",
609
616
  parameters: HISTORY_SCHEMA,
610
617
  prepareArguments(args) {
611
618
  return args === undefined ? {} : args;
package/src/windows.ts CHANGED
@@ -24,9 +24,19 @@ 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
+
31
+ Previous skill reads don’t carry into this window. Read the skills needed for the current task.
32
+ </context_window_guidance>`;
33
+
34
+ const GPT_GUIDANCE = `<context_window_guidance>
35
+ Notes=recoverystate≠diary. One concise authoritative note/task-or-topic, stablepath. Taskcheckpoint=request/constraints/decisions/status/nextsteps/historyIDs. write_file→replace stalestate; mark completion. Existingnotes→link≠copy/summarise. Recording≠implementationpermission.
36
+
37
+ Savebatch@meaningfulmilestones≠every reply/step. Before new_context/handoff: save currentstate→await success; handoff includes checkpointpath. Postrollover: read checkpoint→neededlinks only. In-context notes: reread only if possiblychanged. Missingdetails→history.
38
+
39
+ Prior skillreads≠currentcontext. Read task-relevant skills.
30
40
  </context_window_guidance>`;
31
41
 
32
42
  export function registerWindowRenderer(pi: ExtensionAPI): void {
@@ -152,6 +162,7 @@ export function windowMessage(
152
162
  hint: string,
153
163
  trim: boolean,
154
164
  kind: "window" | "identity" = "window",
165
+ gpt = false,
155
166
  ): CustomMessageEntryDraft {
156
167
  const lines = [
157
168
  `Agent name: ${agent}`,
@@ -164,7 +175,7 @@ export function windowMessage(
164
175
  return {
165
176
  type: "custom_message",
166
177
  customType: WINDOW_MESSAGE,
167
- content: `${GUIDANCE}\n\n<context_window>\n${lines.join("\n")}\n</context_window>`,
178
+ content: `${gpt ? GPT_GUIDANCE : GUIDANCE}\n\n<context_window>\n${lines.join("\n")}\n</context_window>`,
168
179
  display: true,
169
180
  details: {
170
181
  protocol: 1,