@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 +19 -0
- package/README.md +1 -1
- package/package.json +8 -1
- package/src/bridge.ts +6 -2
- package/src/index.ts +34 -12
- package/src/lifecycle.ts +64 -35
- package/src/saved-session.ts +8 -1
- package/src/shared-notes.ts +58 -14
- package/src/tools.ts +43 -12
- package/src/windows.ts +10 -3
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,
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
329
|
-
|
|
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(
|
|
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
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
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(
|
|
144
|
-
|
|
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
|
-
|
|
222
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
357
|
+
this.sendMessage(
|
|
329
358
|
{
|
|
330
359
|
customType: "notes-compaction:checkpoint:v1",
|
|
331
360
|
details: { requestId },
|
package/src/saved-session.ts
CHANGED
|
@@ -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 (
|
|
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();
|
package/src/shared-notes.ts
CHANGED
|
@@ -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 =
|
|
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 =
|
|
165
|
-
|
|
166
|
-
|
|
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
|
-
...
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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(
|
|
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 (
|
|
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(
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
467
|
-
|
|
468
|
-
|
|
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
|
|
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
|
-
|
|
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,
|