@howaboua/pi-notes-compaction 0.0.13 → 0.0.14

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/src/tools.ts CHANGED
@@ -9,14 +9,16 @@ import type { LookupQuery, SharedNotesDetails } from "./bridge.js";
9
9
  import type { HistorySearch } from "./history-search.js";
10
10
  import type { NotesLifecycle } from "./lifecycle.js";
11
11
  import type { createModelRoles } from "./model-roles.js";
12
+ import { NOTES_OUTPUT_SCHEMA } from "./note-result.js";
12
13
  import { createQueryExecutor } from "./query-executor.js";
13
14
  import type { NotesStore } from "./store.js";
14
15
  import {
15
16
  HISTORY_SCHEMA,
16
17
  NEW_CONTEXT_DESCRIPTION,
17
- NEW_CONTEXT_SCHEMA,
18
18
  NOTES_DESCRIPTION,
19
+ NOTES_ROUTING_GUIDELINE,
19
20
  NOTES_SCHEMA,
21
+ newContextSchema,
20
22
  prepareHistoryArguments,
21
23
  prepareNewContextArguments,
22
24
  prepareNotesArguments,
@@ -63,12 +65,14 @@ export function createTools(
63
65
  );
64
66
  };
65
67
  const queries = createQueryExecutor(pi, store, lifecycle, search);
66
- return [
68
+ const tools: ToolDefinition[] = [
67
69
  {
68
70
  name: "notes",
69
71
  label: "notes",
70
72
  description: NOTES_DESCRIPTION,
73
+ promptGuidelines: [NOTES_ROUTING_GUIDELINE],
71
74
  parameters: NOTES_SCHEMA,
75
+ outputSchema: NOTES_OUTPUT_SCHEMA,
72
76
  executionMode: "sequential",
73
77
  prepareArguments: prepareNotesArguments,
74
78
  execute: (callId, input, signal, _update, ctx) =>
@@ -77,7 +81,7 @@ export function createTools(
77
81
  {
78
82
  name: "history",
79
83
  label: "history",
80
- description: "Search earlier conversation",
84
+ description: "Search past chat",
81
85
  parameters: HISTORY_SCHEMA,
82
86
  prepareArguments(args) {
83
87
  return prepareHistoryArguments(args);
@@ -89,7 +93,7 @@ export function createTools(
89
93
  name: "new_context",
90
94
  label: "new_context",
91
95
  description: NEW_CONTEXT_DESCRIPTION,
92
- parameters: NEW_CONTEXT_SCHEMA,
96
+ parameters: newContextSchema([]),
93
97
  prepareArguments: prepareNewContextArguments,
94
98
  exposure: "model-only",
95
99
  executionMode: "sequential",
@@ -107,9 +111,9 @@ export function createTools(
107
111
  started,
108
112
  message: started
109
113
  ? lifecycle.newWindowRequests === "pi-limits"
110
- ? "Window request queued. Pi will check whether enough history can be compacted"
111
- : "A new window will open after this run settles"
112
- : "A checkpoint or rollover is already pending. Save notes and finish your response",
114
+ ? "Window request queued"
115
+ : "New window queued"
116
+ : "Checkpoint or rollover is already pending. Save notes and finish your response",
113
117
  }),
114
118
  ...(started ? { terminate: true } : {}),
115
119
  };
@@ -131,4 +135,14 @@ export function createTools(
131
135
  },
132
136
  },
133
137
  ];
138
+ const newContext = tools.find((tool) => tool.name === "new_context")!;
139
+ let advertisedRoles = "[]";
140
+ roles.onRoleIdsChanged((ids) => {
141
+ const key = JSON.stringify(ids);
142
+ if (key === advertisedRoles) return;
143
+ advertisedRoles = key;
144
+ newContext.parameters = newContextSchema(ids);
145
+ pi.registerTool(newContext);
146
+ });
147
+ return tools;
134
148
  }
@@ -3,7 +3,6 @@ import type {
3
3
  ExtensionAPI,
4
4
  SessionEntry,
5
5
  } from "@earendil-works/pi-coding-agent";
6
- import { keyHint } from "@earendil-works/pi-coding-agent";
7
6
  import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
8
7
  import type { WindowIdentity } from "./bridge.js";
9
8
 
@@ -16,25 +15,37 @@ export interface WindowDetails {
16
15
  trim: boolean;
17
16
  }
18
17
  const GUIDANCE = `<context_window_guidance>
19
- Notes are recovery state, not a diary. Write checkpoints and reports to relative paths in your own notes. Delegates do likewise and return their note paths. 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 to replace stale state and mark completion. Link to existing notes instead of copying or summarising their contents. Recording isn't permission to implement.
18
+ Notes are recovery state, not diary. They use virtual storage, not disk filesystem. Use relative paths when creating.
20
19
 
21
- You must maintain a task checkpoint, updating it at each meaningful milestone and on completion or before switching substantive tasks, even with context room. Don't save 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.
20
+ MUST maintain one authoritative checkpoint per task/topic with request, constraints, decision, status, next steps and relevant history IDs.
22
21
 
23
- Previous skill reads don’t carry into this window. Read the skills needed for the current task.
22
+ Use the notes tool write action to create or replace the checkpoint at milestones, task switches and completion. Use action append to add to it.
23
+
24
+ Subagents MUST maintain their own notes and return paths. For subagent handoffs, include the checkpoint path.
25
+
26
+ Link existing notes instead of duplicating content. Recording does not authorise implementation.
27
+
28
+ Before new_context or a handoff, MUST save the checkpoint with notes. For rollover, call new_context.
29
+
30
+ After rollover, use notes read action to recover the checkpoint, then read only necessary links. SHOULD NOT reread unchanged notes. Use the history tool for missing details.
31
+
32
+ Skill reads do not survive rollover. MUST reread required skills.
24
33
  </context_window_guidance>`;
25
34
 
26
35
  const GPT_GUIDANCE = `<context_window_guidance>
27
- Notes=recovery state≠diary. Checkpoints/reports→write relative paths in own notes. Delegates→same→return note paths. One concise authoritative note per task/topic, stable path. Task checkpoint=request/constraints/decisions/status/next steps/history IDs. write→replace stale state; mark completion. Existing notes→link≠copy/summarise. Recording≠implementation permission.
36
+ Notes=recovery stateNOTdiary. Virtual Notes storageNOTfilesystem. Create notes with relative paths. One authoritative checkpoint per task/topic→request/constraints/decision/status/next steps/history IDs. Existing notes→linkNOTduplicate. RecordingNOTimplementation permission.
37
+
38
+ MUST maintain task checkpoint→update@ milestones, task switches + completion. Notes tool: write→create/replace stale checkpoint; append→add content. Not every reply/step. Subagents MUST maintain own notes→return paths.
28
39
 
29
- Must maintain task checkpoint→update@each meaningful milestone + completion/before switching substantive tasks, even with context room. Not every reply/step. Before new_context/handoff: save current state→await success; handoff includes checkpoint path. Post-rollover: read checkpoint→needed links only. In-context notes: reread only if possibly changed. Missing details→history.
40
+ Before new_context/handoff: MUST save checkpoint via notes. Rollover→call new_context after save; subagent handoff→include checkpoint path. Post-rollover: notes read→checkpoint→necessary links only. SHOULD NOT reread unchanged notes. Missing details→history tool.
30
41
 
31
- Prior skill reads≠current context. Read task-relevant skills.
42
+ Prior skill reads≠current context. MUST reread required skills after rollover.
32
43
  </context_window_guidance>`;
33
44
 
34
45
  export function registerWindowRenderer(pi: ExtensionAPI): void {
35
46
  pi.registerMessageRenderer(
36
47
  WINDOW_MESSAGE,
37
- (message, { expanded, outputPad }, theme) => {
48
+ (message, { expanded, outputPad, keyHint }, theme) => {
38
49
  const details = parseWindowDetails(message.details);
39
50
  if (!details || typeof message.content !== "string") return undefined;
40
51
  const title =
package/src/windows.ts CHANGED
@@ -151,8 +151,8 @@ export class Windows {
151
151
  kind === "task-boundary"
152
152
  ? renderTaskBoundaryReminder(remainingPercent, gpt)
153
153
  : gpt
154
- ? `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context left; save task state via notes→new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`
155
- : `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context remaining. Save the task state in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
154
+ ? `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context left; save checkpoint via notes→new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`
155
+ : `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% context remaining. Save checkpoint with notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
156
156
  display: true,
157
157
  details: {
158
158
  protocol: 1,
package/changelog.ts DELETED
@@ -1,337 +0,0 @@
1
- // Generated extension packages copy this file during changelog:extensions.
2
-
3
- import { randomUUID } from "node:crypto";
4
- import { readFileSync } from "node:fs";
5
- import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
6
- import { dirname, join } from "node:path";
7
- import { fileURLToPath } from "node:url";
8
- import {
9
- DynamicBorder,
10
- type ExtensionAPI,
11
- getAgentDir,
12
- getMarkdownTheme,
13
- } from "@earendil-works/pi-coding-agent";
14
- import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
15
-
16
- const ENTRY_TYPE = "@howaboua/pi-stuff/changelog";
17
- const REGISTRATION_CHANNEL = "@howaboua/pi-stuff/changelog/register/v1";
18
- const STATE_FILENAME = "howaboua-pi-stuff-changelog.json";
19
- const SUPPRESS_KEY = "suppress";
20
- const LOCK_STALE_MS = 30_000;
21
- const LOCK_TIMEOUT_MS = 2_000;
22
-
23
- interface PackageMetadata {
24
- name: string;
25
- version: string;
26
- }
27
-
28
- interface PackageRegistration extends PackageMetadata {
29
- changelogPath: string;
30
- }
31
-
32
- interface RegistrationEvent {
33
- accept: () => void;
34
- registration: PackageRegistration;
35
- }
36
-
37
- interface ChangelogEntry {
38
- content: string;
39
- version: string;
40
- }
41
-
42
- interface ChangelogEntryData {
43
- markdown: string;
44
- }
45
-
46
- type ChangelogState = Record<string, boolean | string>;
47
-
48
- function packageRegistration(): PackageRegistration {
49
- const packageDirectory = fileURLToPath(new URL(".", import.meta.url));
50
- const metadata = JSON.parse(
51
- readFileSync(join(packageDirectory, "package.json"), "utf8"),
52
- ) as Partial<PackageMetadata>;
53
- if (typeof metadata.name !== "string" || typeof metadata.version !== "string")
54
- throw new Error(`Invalid package metadata in ${packageDirectory}`);
55
- return {
56
- name: metadata.name,
57
- version: metadata.version,
58
- changelogPath: join(packageDirectory, "CHANGELOG.md"),
59
- };
60
- }
61
-
62
- function isRegistrationEvent(value: unknown): value is RegistrationEvent {
63
- if (!value || typeof value !== "object") return false;
64
- const event = value as Partial<RegistrationEvent>;
65
- return (
66
- typeof event.accept === "function" &&
67
- typeof event.registration?.name === "string" &&
68
- typeof event.registration.version === "string" &&
69
- typeof event.registration.changelogPath === "string"
70
- );
71
- }
72
-
73
- function parseChangelog(markdown: string): ChangelogEntry[] {
74
- const entries: ChangelogEntry[] = [];
75
- let currentLines: string[] = [];
76
- let currentVersion: string | undefined;
77
-
78
- for (const line of markdown.split("\n")) {
79
- const version = line.match(/^##\s+\[?(\d+\.\d+\.\d+)\]?(?:\s.*)?$/)?.[1];
80
- if (version) {
81
- if (currentVersion)
82
- entries.push({
83
- content: currentLines.join("\n").trim(),
84
- version: currentVersion,
85
- });
86
- currentVersion = version;
87
- currentLines = [line];
88
- } else if (currentVersion) {
89
- currentLines.push(line);
90
- }
91
- }
92
-
93
- if (currentVersion)
94
- entries.push({
95
- content: currentLines.join("\n").trim(),
96
- version: currentVersion,
97
- });
98
- return entries;
99
- }
100
-
101
- function compareVersions(left: string, right: string): number {
102
- const leftParts = left.split(".").map(Number);
103
- const rightParts = right.split(".").map(Number);
104
- for (let index = 0; index < 3; index++) {
105
- const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
106
- if (difference !== 0) return difference;
107
- }
108
- return 0;
109
- }
110
-
111
- function isStableVersion(version: string): boolean {
112
- return /^\d+\.\d+\.\d+$/.test(version);
113
- }
114
-
115
- function statePath(): string {
116
- return join(getAgentDir(), STATE_FILENAME);
117
- }
118
-
119
- async function readState(path: string): Promise<ChangelogState> {
120
- let text: string;
121
- try {
122
- text = await readFile(path, "utf8");
123
- } catch (error) {
124
- if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
125
- throw error;
126
- }
127
- const parsed = JSON.parse(text) as unknown;
128
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
129
- throw new Error(`${path} must contain a JSON object`);
130
- for (const [name, value] of Object.entries(parsed)) {
131
- if (name === SUPPRESS_KEY) {
132
- if (typeof value !== "boolean")
133
- throw new Error(`${path} ${SUPPRESS_KEY} must be a boolean`);
134
- } else if (typeof value !== "string") {
135
- throw new Error(`${path} version for ${name} must be a string`);
136
- }
137
- }
138
- return parsed as ChangelogState;
139
- }
140
-
141
- async function acquireLock(path: string): Promise<() => Promise<void>> {
142
- const deadline = Date.now() + LOCK_TIMEOUT_MS;
143
- while (true) {
144
- try {
145
- await mkdir(path);
146
- return () => rm(path, { force: true, recursive: true });
147
- } catch (error) {
148
- if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
149
- const info = await stat(path).catch(() => undefined);
150
- if (info && Date.now() - info.mtimeMs > LOCK_STALE_MS) {
151
- await rm(path, { force: true, recursive: true });
152
- continue;
153
- }
154
- if (Date.now() >= deadline)
155
- throw new Error(`Timed out waiting for ${path}`);
156
- await new Promise((resolve) => setTimeout(resolve, 20));
157
- }
158
- }
159
- }
160
-
161
- async function writeState(path: string, state: ChangelogState): Promise<void> {
162
- await mkdir(dirname(path), { mode: 0o700, recursive: true });
163
- const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
164
- try {
165
- const ordered = Object.fromEntries(
166
- Object.entries(state).sort(([left], [right]) =>
167
- left.localeCompare(right),
168
- ),
169
- );
170
- await writeFile(temporaryPath, `${JSON.stringify(ordered, null, 2)}\n`, {
171
- encoding: "utf8",
172
- mode: 0o600,
173
- });
174
- await rename(temporaryPath, path);
175
- } catch (error) {
176
- await rm(temporaryPath, { force: true });
177
- throw error;
178
- }
179
- }
180
-
181
- function packageMarkdown(
182
- registration: PackageRegistration,
183
- entries: ChangelogEntry[],
184
- ): string {
185
- const body = (entry: ChangelogEntry) =>
186
- entry.content
187
- .replace(/^##[^\n]*\n*/, "")
188
- .replace(/^###\s+(?:Changes|Minor Changes|Patch Changes)\s*\n*/gim, "")
189
- .replace(/^###\s+(.+)$/gm, "**$1**");
190
- if (entries.length === 1) {
191
- const [entry] = entries;
192
- if (!entry) return "";
193
- return `## ${registration.name} ${entry.version}\n\n${body(entry)}`;
194
- }
195
- return [
196
- `## ${registration.name}`,
197
- ...entries.map((entry) => `**${entry.version}**\n\n${body(entry)}`),
198
- ].join("\n\n");
199
- }
200
-
201
- async function claimUpdates(
202
- registrations: Iterable<PackageRegistration>,
203
- ): Promise<{ errors: string[]; markdown?: string }> {
204
- const stableRegistrations = [...registrations]
205
- .filter((registration) => isStableVersion(registration.version))
206
- .sort((left, right) => left.name.localeCompare(right.name));
207
- if (stableRegistrations.length === 0) return { errors: [] };
208
- const path = statePath();
209
- await mkdir(dirname(path), { mode: 0o700, recursive: true });
210
- const release = await acquireLock(`${path}.lock`);
211
- try {
212
- const state = await readState(path);
213
- const errors: string[] = [];
214
- const sections: string[] = [];
215
- let changed = false;
216
- if (state[SUPPRESS_KEY] === true) {
217
- for (const registration of stableRegistrations) {
218
- const seenVersion = state[registration.name];
219
- if (
220
- typeof seenVersion !== "string" ||
221
- compareVersions(registration.version, seenVersion) > 0
222
- ) {
223
- state[registration.name] = registration.version;
224
- changed = true;
225
- }
226
- }
227
- if (changed) await writeState(path, state);
228
- return { errors };
229
- }
230
- for (const registration of stableRegistrations) {
231
- const seenVersion = state[registration.name];
232
- if (
233
- typeof seenVersion === "string" &&
234
- compareVersions(registration.version, seenVersion) <= 0
235
- )
236
- continue;
237
- try {
238
- const entries = parseChangelog(
239
- await readFile(registration.changelogPath, "utf8"),
240
- ).filter(
241
- (entry) =>
242
- compareVersions(entry.version, registration.version) <= 0 &&
243
- (typeof seenVersion === "string"
244
- ? compareVersions(entry.version, seenVersion) > 0
245
- : entry.version === registration.version),
246
- );
247
- if (entries.length === 0) {
248
- errors.push(
249
- `No ${registration.version} changelog entry found for ${registration.name}`,
250
- );
251
- continue;
252
- }
253
- sections.push(packageMarkdown(registration, entries));
254
- state[registration.name] = registration.version;
255
- changed = true;
256
- } catch (error) {
257
- errors.push(
258
- `Could not read the ${registration.name} changelog: ${error instanceof Error ? error.message : String(error)}`,
259
- );
260
- }
261
- }
262
- if (changed) await writeState(path, state);
263
- return {
264
- errors,
265
- ...(sections.length > 0 ? { markdown: sections.join("\n\n") } : {}),
266
- };
267
- } finally {
268
- await release();
269
- }
270
- }
271
-
272
- function registerCoordinator(
273
- pi: ExtensionAPI,
274
- registration: PackageRegistration,
275
- ): void {
276
- let accepted = false;
277
- pi.events.emit(REGISTRATION_CHANNEL, {
278
- registration,
279
- accept: () => {
280
- accepted = true;
281
- },
282
- } satisfies RegistrationEvent);
283
- if (accepted) return;
284
-
285
- const registrations = new Map([[registration.name, registration]]);
286
- pi.events.on(REGISTRATION_CHANNEL, (value) => {
287
- if (!isRegistrationEvent(value)) return;
288
- registrations.set(value.registration.name, value.registration);
289
- value.accept();
290
- });
291
- pi.registerEntryRenderer<ChangelogEntryData>(
292
- ENTRY_TYPE,
293
- (entry, _options, theme) => {
294
- if (!entry.data) return undefined;
295
- const container = new Container();
296
- container.addChild(new DynamicBorder());
297
- container.addChild(
298
- new Text(theme.bold(theme.fg("accent", "What's New")), 1, 0),
299
- );
300
- container.addChild(new Spacer(1));
301
- container.addChild(
302
- new Markdown(entry.data.markdown.trim(), 1, 0, getMarkdownTheme()),
303
- );
304
- container.addChild(new Spacer(1));
305
- container.addChild(new DynamicBorder());
306
- return container;
307
- },
308
- );
309
- pi.on("session_start", async (event, ctx) => {
310
- if (event.reason === "reload" || ctx.mode !== "tui") return;
311
- if (
312
- ctx.sessionManager
313
- .getEntries()
314
- .some((entry) =>
315
- ["branch_summary", "compaction", "message"].includes(entry.type),
316
- )
317
- )
318
- return;
319
- try {
320
- const update = await claimUpdates(registrations.values());
321
- if (update.markdown)
322
- pi.appendEntry<ChangelogEntryData>(ENTRY_TYPE, {
323
- markdown: update.markdown,
324
- });
325
- for (const error of update.errors) ctx.ui.notify(error, "warning");
326
- } catch (error) {
327
- ctx.ui.notify(
328
- `Could not update Howaboua changelog state: ${error instanceof Error ? error.message : String(error)}`,
329
- "warning",
330
- );
331
- }
332
- });
333
- }
334
-
335
- export default function howabouaPackageChangelog(pi: ExtensionAPI): void {
336
- registerCoordinator(pi, packageRegistration());
337
- }