@howaboua/pi-notes-compaction 0.0.6 → 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,24 @@
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
+
18
+ ## 0.0.7
19
+
20
+ - Shared local agent history now remains readable after its owner closes or Shepherdr is removed.
21
+
3
22
  ## 0.0.6
4
23
 
5
24
  - Requires Pi 1.2.0 or newer.
package/README.md CHANGED
@@ -18,7 +18,7 @@ With Pi Codex Conversion 3.0.48 or newer, local notes work alongside Codex tools
18
18
 
19
19
  The agent keeps the familiar `notes`, `history`, `new_context` and `get_context_remaining` tools. Notes use virtual paths. Relative paths belong to the current agent. History searches the selected Pi session branch, including earlier windows. It does not create a second transcript archive.
20
20
 
21
- Previously shared local notes remain readable after the other agent closes or Shepherdr is removed. Notes follows the saved family relationships and attachment aliases without requiring PCC. Reads use the other session's saved branch. When only a retained attachment snapshot is available, the result identifies it as detached or potentially stale. Cross-agent writes and history still require their live routing service.
21
+ Previously shared local notes and history remain readable after the other agent closes or Shepherdr is removed. Notes follows the saved family relationships and attachment aliases without requiring PCC. Reads use the other session's saved branch and preserve its history IDs. When only a retained attachment snapshot is available, notes identify it as detached or potentially stale. Snapshots do not contain history. Cross-agent writes still require their live routing service. Saved history reads do not fetch or decrypt remote history.
22
22
 
23
23
  By default, `new_context` starts a fresh window without generating a summary. The agent receives recent note paths, and Pi's saved history remains available for lookup.
24
24
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-notes-compaction",
3
- "version": "0.0.6",
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 },
@@ -70,6 +70,7 @@ async function* reverseLines(file: FileHandle, size: number) {
70
70
  export async function readSavedNotesSession(
71
71
  path: string,
72
72
  signal?: AbortSignal,
73
+ history = false,
73
74
  ): Promise<SavedNotesSession> {
74
75
  signal?.throwIfAborted();
75
76
  const file = await open(path, "r");
@@ -104,7 +105,13 @@ export async function readSavedNotesSession(
104
105
  else if (active && NOTE_ENTRIES.has(entry.customType))
105
106
  branch.push(entry);
106
107
  else continue;
107
- } else if (active && Check(Handoff, entry)) branch.push(entry);
108
+ } else if (
109
+ active &&
110
+ history &&
111
+ (entry.type === "message" || entry.type === "custom_message")
112
+ )
113
+ branch.push(entry as SessionEntry);
114
+ else if (active && Check(Handoff, entry)) branch.push(entry);
108
115
  else continue;
109
116
  }
110
117
  const after = await file.stat();
@@ -5,6 +5,7 @@ import type {
5
5
  } from "@earendil-works/pi-coding-agent";
6
6
  import { type Static, Type } from "typebox";
7
7
  import { Check } from "typebox/value";
8
+ import { useHistory } from "./history.js";
8
9
  import { collectNotes, normalizeNoteParams, readNotes } from "./notes.js";
9
10
  import {
10
11
  readSavedNotesSession,
@@ -152,18 +153,44 @@ export async function readSharedNotes(
152
153
  store: Pick<NotesStore, "read">,
153
154
  params: Record<string, unknown>,
154
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,
155
175
  ): Promise<Record<string, unknown> | undefined> {
156
176
  if (
177
+ namespace === "notes" &&
157
178
  !["read_file", "list_files_by_prefix", "search_contents"].includes(
158
179
  String(params["action"]),
159
180
  )
160
181
  )
161
182
  return;
162
- const path = params["path"] ?? params["prefix"] ?? params["path_prefix"];
183
+ const path =
184
+ namespace === "history"
185
+ ? params["agent_name"]
186
+ : (params["path"] ?? params["prefix"] ?? params["path_prefix"]);
163
187
  if (typeof path !== "string" || !path.startsWith("/")) return;
164
- const target = /^(\/root(?:\/[a-zA-Z0-9_-]+)*?)\/notes(?:\/|$)/.exec(
165
- path,
166
- )?.[1];
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];
167
194
  if (!target) return;
168
195
  const outputAgent = target;
169
196
  const current: SavedNotesSession = {
@@ -180,11 +207,13 @@ export async function readSharedNotes(
180
207
  native: string,
181
208
  ) {
182
209
  return {
183
- ...readNotes(
184
- collectNotes(store, session.branch),
185
- normalizeNoteParams(query, native),
186
- outputAgent,
187
- ),
210
+ ...(namespace === "history"
211
+ ? useHistory(session.branch, query, session.threadId)
212
+ : readNotes(
213
+ collectNotes(store, session.branch),
214
+ normalizeNoteParams(query, native),
215
+ outputAgent,
216
+ )),
188
217
  source: "saved-session",
189
218
  read_only: true,
190
219
  remote: { state: "not_fetched" },
@@ -201,10 +230,14 @@ export async function readSharedNotes(
201
230
  retained?: unknown,
202
231
  detached = false,
203
232
  ): Promise<Record<string, unknown> | undefined> {
204
- if (file && !detached) {
233
+ if (file && (!detached || namespace === "history")) {
205
234
  let saved: SavedNotesSession | undefined;
206
235
  try {
207
- saved = await readSavedNotesSession(file, signal);
236
+ saved = await readSavedNotesSession(
237
+ file,
238
+ signal,
239
+ namespace === "history",
240
+ );
208
241
  } catch (error) {
209
242
  signal?.throwIfAborted();
210
243
  if (
@@ -212,7 +245,8 @@ export async function readSharedNotes(
212
245
  error instanceof Error &&
213
246
  "code" in error &&
214
247
  error.code === "ENOENT" &&
215
- retained !== undefined
248
+ retained !== undefined &&
249
+ namespace === "notes"
216
250
  )
217
251
  )
218
252
  throw error;
@@ -223,7 +257,11 @@ export async function readSharedNotes(
223
257
  return resolve(saved, destination, query);
224
258
  }
225
259
  }
226
- if (destination !== identity.agentName || !Check(Snapshot, retained))
260
+ if (
261
+ namespace === "history" ||
262
+ destination !== identity.agentName ||
263
+ !Check(Snapshot, retained)
264
+ )
227
265
  return;
228
266
  const entry: SessionEntry = {
229
267
  type: "custom",
@@ -260,6 +298,7 @@ export async function readSharedNotes(
260
298
  const identity = savedNotesIdentity(session);
261
299
  if (identity.agentName === destination) {
262
300
  if (
301
+ namespace === "notes" &&
263
302
  identity.storage === "remote" &&
264
303
  !session.branch.some(
265
304
  (entry) =>
@@ -332,7 +371,11 @@ export async function readSharedNotes(
332
371
  );
333
372
  if (Check(Member, member)) {
334
373
  if (member.machine !== "local") return;
335
- const saved = await readSavedNotesSession(member.sessionFile, signal);
374
+ const saved = await readSavedNotesSession(
375
+ member.sessionFile,
376
+ signal,
377
+ namespace === "history",
378
+ );
336
379
  const child = savedNotesIdentity(saved);
337
380
  if (
338
381
  child.sessionId !== identity.sessionId ||
@@ -349,6 +392,7 @@ export async function readSharedNotes(
349
392
  const saved = await readSavedNotesSession(
350
393
  routing.parent.slice(0, -".shepherdr-context.json".length),
351
394
  signal,
395
+ namespace === "history",
352
396
  );
353
397
  const parent = savedNotesIdentity(saved);
354
398
  if (
package/src/tools.ts CHANGED
@@ -24,7 +24,11 @@ import {
24
24
  sourceSessionIds,
25
25
  useNotes,
26
26
  } from "./notes.js";
27
- import { readSharedNotes, sharedNotesUnavailable } from "./shared-notes.js";
27
+ import {
28
+ readSharedHistory,
29
+ readSharedNotes,
30
+ sharedNotesUnavailable,
31
+ } from "./shared-notes.js";
28
32
  import type { NotesStore } from "./store.js";
29
33
 
30
34
  const NOTES_ACTIONS = [
@@ -42,9 +46,8 @@ const HISTORY_ACTIONS = [
42
46
  "read_item",
43
47
  "search_contents",
44
48
  ] as const;
45
- export const NOTES_USAGE =
46
- "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)";
47
- export const HISTORY_USAGE = "await tools.history() // help";
49
+ export const NOTES_USAGE = "await tools.notes()";
50
+ export const HISTORY_USAGE = "await tools.history()";
48
51
  const STRING = Type.Optional(Type.String());
49
52
  const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
50
53
  const NULLABLE_STRING = Type.Optional(Type.Union([Type.String(), Type.Null()]));
@@ -224,13 +227,19 @@ function discovery(
224
227
  ),
225
228
  ...(namespace === "notes"
226
229
  ? {
230
+ writes: "write_file replaces; append_to_file adds",
231
+ paths:
232
+ "Relative uses current agent; cross-agent uses <agent>/notes[/path]",
227
233
  usage: '{ "action": "read_file", "path": "checkpoint" }',
228
234
  ranges:
229
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",
230
236
  defaults:
231
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",
232
238
  }
233
- : {}),
239
+ : {
240
+ usage:
241
+ "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
242
+ }),
234
243
  });
235
244
  }
236
245
  return undefined;
@@ -463,9 +472,33 @@ function createQueryExecutor(
463
472
  assertActive();
464
473
  const params = relevant("history", input);
465
474
  const query = { namespace: "history", params } as const;
466
- const routed =
467
- !shared && (await lifecycle.bridge?.route?.(query, callId, ctx, signal));
468
- if (routed) return routed;
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
+ }
469
502
  if (params["agent_name"] && params["agent_name"] !== lifecycle.agent(ctx))
470
503
  throw new Error(
471
504
  "That agent's history is not available here. Omit agent_name to search this session.",
@@ -530,8 +563,7 @@ export function createTools(
530
563
  {
531
564
  name: "notes",
532
565
  label: "notes",
533
- description:
534
- "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",
535
567
  parameters: NOTES_SCHEMA,
536
568
  executionMode: "sequential",
537
569
  prepareArguments(args) {
@@ -576,8 +608,7 @@ export function createTools(
576
608
  {
577
609
  name: "history",
578
610
  label: "history",
579
- description:
580
- "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
611
+ description: "Search earlier conversation",
581
612
  parameters: HISTORY_SCHEMA,
582
613
  prepareArguments(args) {
583
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,