@howaboua/pi-notes-compaction 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @howaboua/pi-notes-compaction
 
+## 0.0.5
+
+- We've been informed that Astra and Sol currently retain their prompt caches for around an hour. If you use notes-managed idle rollover, consider increasing it from 25 to 55 minutes. Cache retention can vary. YMMV. We'll keep monitoring. Please share your cache-retention and long-context quota observations in [the feedback thread](https://github.com/IgorWarzocha/howaboua-pi-stuff/issues/508).
+
+  Added configurable task-boundary reminders and a clearer settings layout.
+
+  - Added optional reminders at preset or custom token counts when context capacity exceeds 272k, showing the remaining percentage.
+  - Status text and keyboard hints now wrap to fit narrow terminals.
+  - Notes help now lists required arguments. Writes accept `content` when `text` is omitted.
+  - Fixed fresh worker startup with Notes enabled.
+
 ## 0.0.4
 
 - Fixed note queries and manual context rollover with Codex Conversion.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@howaboua/pi-notes-compaction",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"publishConfig": {
 		"access": "public"
 	},

package/src/bridge.ts

@@ -1,6 +1,7 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type {
 	AgentToolResult,
+	CustomMessageEntryDraft,
 	ExtensionAPI,
 	ExtensionContext,
 	SessionBeforeCompactEvent,
@@ -86,6 +87,8 @@ export interface NotesOwner {
 
 export interface NotesBridge {
 	protocol: 1;
+	/** Preserve the owner's chronological entry while enabling developer-role delivery. */
+	prepareReminder?(entry: CustomMessageEntryDraft): CustomMessageEntryDraft;
 	/** Synchronous atomic handoff. No legacy registrations or lifecycle owners remain active. */
 	claim(owner: NotesOwner):
 		| {

package/src/index.ts

@@ -54,6 +54,15 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 					entry.customType === "@howaboua/pi-stuff/changelog"
 				)
 					return true;
+				// PCC links the fresh worker before binding its shared notes family.
+				if (
+					entry.type === "custom" &&
+					entry.customType === "codex-agent-relationship"
+				)
+					return (
+						(entry.data as { threadId?: unknown } | undefined)?.threadId ===
+						ctx.sessionManager.getSessionId()
+					);
 				// Herdr activation persists its empty registry before first task delivery.
 				if (
 					entry.type === "custom" &&
@@ -168,10 +177,29 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 			);
 		}
 	});
-	pi.on("turn_end", (_event, ctx) => {
-		if (!lifecycle.active || lifecycle.fresh(ctx, lifecycle.runId)) return;
-		const reminder = lifecycle.windows.reminder(ctx);
-		return reminder ? { entries: [reminder] } : undefined;
+	pi.on("turn_end", (event, ctx) => {
+		if (!lifecycle.active) return;
+		const reminder = lifecycle.windows.reminder(
+			ctx,
+			event.message.role === "assistant" &&
+				!ctx.signal?.aborted &&
+				!["error", "length", "aborted"].includes(event.message.stopReason) &&
+				event.toolResults.length > 0 &&
+				pi.getActiveTools().includes("new_context")
+				? lifecycle.taskBoundaryReminder
+				: 0,
+			!lifecycle.fresh(ctx, lifecycle.runId),
+		);
+		return reminder
+			? {
+					entries: [
+						...event.entries,
+						windowDetails(reminder)?.kind === "task-boundary"
+							? (lifecycle.bridge?.prepareReminder?.(reminder) ?? reminder)
+							: reminder,
+					],
+				}
+			: undefined;
 	});
 	pi.on("context", (event, ctx) => {
 		if (!lifecycle.active) return;
@@ -240,8 +268,10 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 					settings: () => ({
 						normalCompaction: lifecycle.normalCompaction,
 						idleMinutes: lifecycle.idleMinutes,
+						taskBoundaryReminder: lifecycle.taskBoundaryReminder,
 					}),
 					save,
+					settingsPath,
 					prune,
 					status: () => {
 						const counts = store.status();

package/src/lifecycle.ts

@@ -50,6 +50,7 @@ export class NotesLifecycle {
 	active = false;
 	normalCompaction = false;
 	idleMinutes: IdleMinutes = 0;
+	taskBoundaryReminder = 0;
 	bridge: NotesBridge | undefined;
 	runId = "";
 	private checkpoint: Checkpoint | undefined;

package/src/settings-screen.ts

@@ -2,13 +2,19 @@ import {
 	type ExtensionContext,
 	getSettingsListTheme,
 } from "@earendil-works/pi-coding-agent";
-import { SettingsList, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	SettingsList,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
 import { IDLE_MINUTES, type NotesSettings } from "./settings.js";
+import { TASK_BOUNDARY_PRESETS, taskBoundaryLabel } from "./task-boundary.js";
 
 export async function openNotesSettings(
 	ctx: ExtensionContext,
 	options: {
 		settings: () => NotesSettings;
+		settingsPath: string;
 		save: (settings: NotesSettings) => void;
 		status: () => string[];
 		prune: () => Promise<void>;
@@ -31,6 +37,17 @@ export async function openNotesSettings(
 							currentValue: settings.normalCompaction ? "on" : "off",
 							values: ["off", "on"],
 						},
+						{
+							id: "taskBoundaryReminder",
+							label: "Task-boundary reminder",
+							description:
+								"Suggest a separate-task rollover after this many used tokens, only with active capacity above 272k. Custom: edit taskBoundaryReminder in the notes settings JSON (whole tokens); 0 is off.",
+							currentValue: taskBoundaryLabel(settings.taskBoundaryReminder),
+							values: [
+								...TASK_BOUNDARY_PRESETS.map(taskBoundaryLabel),
+								"custom (edit JSON)",
+							],
+						},
 						{
 							id: "idle",
 							label: "Idle rollover",
@@ -56,9 +73,31 @@ export async function openNotesSettings(
 							return;
 						}
 						const current = options.settings();
+						if (
+							id === "taskBoundaryReminder" &&
+							value === "custom (edit JSON)"
+						) {
+							ctx.ui.notify(
+								`Set taskBoundaryReminder to a positive whole token count in ${options.settingsPath}, then reload Pi. 0 is off.`,
+								"info",
+							);
+							list.updateValue(
+								id,
+								taskBoundaryLabel(current.taskBoundaryReminder),
+							);
+							return;
+						}
 						try {
 							if (id === "compact")
 								options.save({ ...current, normalCompaction: value === "on" });
+							else if (id === "taskBoundaryReminder")
+								options.save({
+									...current,
+									taskBoundaryReminder:
+										TASK_BOUNDARY_PRESETS.find(
+											(tokens) => taskBoundaryLabel(tokens) === value,
+										) ?? current.taskBoundaryReminder,
+								});
 							else {
 								const idleMinutes = IDLE_MINUTES.find(
 									(minutes) => idleValue(minutes) === value,
@@ -69,11 +108,13 @@ export async function openNotesSettings(
 						} catch (error) {
 							list.updateValue(
 								id,
-								id === "compact"
-									? current.normalCompaction
-										? "on"
-										: "off"
-									: idleValue(current.idleMinutes),
+								id === "taskBoundaryReminder"
+									? taskBoundaryLabel(current.taskBoundaryReminder)
+									: id === "compact"
+										? current.normalCompaction
+											? "on"
+											: "off"
+										: idleValue(current.idleMinutes),
 							);
 							ctx.ui.notify(
 								`Could not save notes settings: ${String(error)}`,
@@ -86,20 +127,36 @@ export async function openNotesSettings(
 					{ enableSearch: false },
 				);
 				return {
-					render: (width) =>
-						[
-							theme.fg("accent", "Notes & context"),
-							...status.map((line) => theme.fg("dim", line)),
+					render: (width) => {
+						const wrap = (text: string) =>
+							wrapTextWithAnsi(text, Math.max(1, width - 2)).map(
+								(line) => `  ${line}`,
+							);
+						const rule = theme.fg("accent", "─".repeat(Math.max(0, width)));
+						return [
+							rule,
+							`  ${theme.bold("Notes & context")}`,
+							"",
+							...status.flatMap((line) =>
+								wrap(line).map((part) => theme.fg("dim", part)),
+							),
 							"",
-							...list.render(width),
+							...list.render(width).slice(0, -2),
 							"",
-							theme.fg(
-								"dim",
-								"↑↓ navigate · Enter/Space change · Esc close · saved immediately",
+							...wrap("↑/↓ select · Enter/Space change · Esc close").map(
+								(line) => theme.fg("dim", line),
 							),
-						].map((line) => truncateToWidth(line, width)),
+							...wrap("Settings saved immediately").map((line) =>
+								theme.fg("dim", line),
+							),
+							rule,
+						].map((line) => truncateToWidth(line, width, ""));
+					},
 					invalidate: () => list.invalidate(),
-					handleInput: (data) => list.handleInput(data),
+					handleInput: (data) => {
+						list.handleInput(data);
+						tui.requestRender();
+					},
 				};
 			},
 		);

package/src/settings.ts

@@ -6,6 +6,7 @@ export type IdleMinutes = (typeof IDLE_MINUTES)[number];
 export interface NotesSettings {
 	normalCompaction: boolean;
 	idleMinutes: IdleMinutes;
+	taskBoundaryReminder: number;
 }
 
 export function readSettings(path: string): NotesSettings {
@@ -14,7 +15,11 @@ export function readSettings(path: string): NotesSettings {
 		source = readFileSync(path, "utf8");
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT")
-			return { normalCompaction: false, idleMinutes: 0 };
+			return {
+				normalCompaction: false,
+				idleMinutes: 0,
+				taskBoundaryReminder: 0,
+			};
 		throw error;
 	}
 	const settings: unknown = JSON.parse(source);
@@ -28,6 +33,16 @@ export function readSettings(path: string): NotesSettings {
 			"Invalid notes settings. Save a setting in /notes, then reload Pi.",
 		);
 	const idleMinutes = "idleMinutes" in settings ? settings.idleMinutes : 0;
+	const taskBoundaryReminder =
+		"taskBoundaryReminder" in settings ? settings.taskBoundaryReminder : 0;
+	if (
+		typeof taskBoundaryReminder !== "number" ||
+		!Number.isSafeInteger(taskBoundaryReminder) ||
+		taskBoundaryReminder < 0
+	)
+		throw new Error(
+			"Invalid task-boundary reminder setting. Save a setting in /notes, then reload Pi.",
+		);
 	if (!IDLE_MINUTES.some((value) => value === idleMinutes))
 		throw new Error(
 			"Invalid idle rollover interval. Choose off, 5, 15, 25 or 55 minutes.",
@@ -35,6 +50,7 @@ export function readSettings(path: string): NotesSettings {
 	return {
 		normalCompaction: settings.normalCompaction,
 		idleMinutes: idleMinutes as IdleMinutes,
+		taskBoundaryReminder,
 	};
 }
 

package/src/task-boundary.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function renderTaskBoundaryReminder(remainingPercent: number): string {
+	return `<context_window_reminder>\nThis window is approaching the recommended token budget. You still have ${remainingPercent}% of your context window remaining, so there is no need to start a new window immediately. If you are working through a sequence of tasks toward a larger goal, finish the current task, save a checkpoint, and start a new window before continuing with the next task. Otherwise, continue here.\n</context_window_reminder>`;
+}
+
+export const TASK_BOUNDARY_PRESETS = [
+	0, 250_000, 300_000, 400_000, 450_000,
+] as const;
+export function taskBoundaryLabel(tokens: number): string {
+	return tokens === 0
+		? "off"
+		: TASK_BOUNDARY_PRESETS.some((value) => value === tokens)
+			? `${tokens / 1000}k`
+			: "custom (edit JSON)";
+}
+export function taskBoundaryEligible(
+	ctx: ExtensionContext,
+	threshold: number,
+	tokens = ctx.getContextUsage()?.tokens,
+): boolean {
+	const capacity =
+		ctx.getContextUsage()?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+	return (
+		threshold > 0 &&
+		Number.isFinite(capacity) &&
+		capacity > 272_000 &&
+		typeof tokens === "number" &&
+		Number.isFinite(tokens) &&
+		tokens >= threshold
+	);
+}

package/src/tools.ts

@@ -41,7 +41,8 @@ const HISTORY_ACTIONS = [
 	"read_item",
 	"search_contents",
 ] as const;
-export const NOTES_USAGE = "await tools.notes() // help";
+export const NOTES_USAGE =
+	"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)";
 export const HISTORY_USAGE = "await tools.history() // help";
 const STRING = Type.Optional(Type.String());
 const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
@@ -526,6 +527,14 @@ export function createTools(
 						'Supply an action object: await tools.notes({ action: "read_file", path: "checkpoint" }); tools.notes() returns help',
 					);
 				const params = { ...args } as Record<string, unknown>;
+				if (
+					(params["action"] === "write_file" ||
+						params["action"] === "append_to_file") &&
+					"content" in params
+				) {
+					if (!("text" in params)) params["text"] = params["content"];
+					delete params["content"];
+				}
 				if (
 					params["action"] === "list_files_by_prefix" &&
 					params["max_files"] !== undefined

package/src/windows.ts

@@ -10,12 +10,16 @@ import type {
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
 import type { WindowIdentity } from "./bridge.js";
+import {
+	renderTaskBoundaryReminder,
+	taskBoundaryEligible,
+} from "./task-boundary.js";
 
 export const WINDOW_MESSAGE = "notes-compaction:window:v1";
 export const SETTLEMENT_ENTRY = "notes-compaction:settled:v1";
 export interface WindowDetails {
 	protocol: 1;
-	kind: "window" | "identity" | "reminder" | "urgent";
+	kind: "window" | "identity" | "reminder" | "urgent" | "task-boundary";
 	identity: WindowIdentity;
 	trim: boolean;
 }
@@ -32,11 +36,13 @@ export function registerWindowRenderer(pi: ExtensionAPI): void {
 			const details = parseWindowDetails(message.details);
 			if (!details || typeof message.content !== "string") return undefined;
 			const title =
-				details.kind === "urgent"
-					? "Context nearly full · Save notes and start a new window now"
-					: details.kind === "reminder"
-						? "Context checkpoint reminder · Save notes and start a new window"
-						: `Context window ${details.identity.windowNumber + 1} · Notes and history`;
+				details.kind === "task-boundary"
+					? "Task-boundary reminder"
+					: details.kind === "urgent"
+						? "Context nearly full · Save notes and start a new window now"
+						: details.kind === "reminder"
+							? "Context checkpoint reminder · Save notes and start a new window"
+							: `Context window ${details.identity.windowNumber + 1} · Notes and history`;
 			const box = new Box(outputPad, 1, (text) =>
 				theme.bg("customMessageBg", text),
 			);
@@ -85,7 +91,7 @@ function parseWindowDetails(value: unknown): WindowDetails | undefined {
 	if (
 		details.protocol !== 1 ||
 		!ids ||
-		!["window", "identity", "reminder", "urgent"].includes(
+		!["window", "identity", "reminder", "urgent", "task-boundary"].includes(
 			details.kind ?? "",
 		) ||
 		typeof details.trim !== "boolean"
@@ -100,7 +106,9 @@ function parseWindowDetails(value: unknown): WindowDetails | undefined {
 }
 
 /** Understand previous PCC window IDs for familiar history lookup, without importing its runtime. */
-export function windowDetails(entry: SessionEntry): WindowDetails | undefined {
+export function windowDetails(
+	entry: SessionEntry | CustomMessageEntryDraft,
+): WindowDetails | undefined {
 	if (entry.type !== "custom_message") return;
 	return messageWindowDetails(entry.customType, entry.details);
 }
@@ -122,14 +130,14 @@ function messageWindowDetails(
 		!details ||
 		typeof details !== "object" ||
 		!("kind" in details) ||
-		details.kind !== "window"
+		(details.kind !== "window" && details.kind !== "task-boundary")
 	)
 		return;
 	const ids = identity(details);
 	return ids
 		? {
 				protocol: 1,
-				kind: "window",
+				kind: details.kind,
 				identity: ids,
 				trim:
 					"trimPreviousWindow" in details &&
@@ -182,13 +190,18 @@ export class Windows {
 				this.compactedSinceBoundary = false;
 			} else if (
 				details &&
-				(details.kind === "reminder" || details.kind === "urgent")
+				(details.kind === "reminder" ||
+					details.kind === "urgent" ||
+					details.kind === "task-boundary")
 			)
 				this.reminders.add(
 					`${details.identity.currentWindowId}:${details.kind}`,
 				);
 			if (entry.type === "compaction") {
-				this.reminders.clear();
+				// Compaction frees capacity, but does not create a new window identity.
+				this.reminders = new Set(
+					[...this.reminders].filter((key) => key.endsWith(":task-boundary")),
+				);
 				this.compactedSinceBoundary = true;
 			}
 		}
@@ -226,21 +239,47 @@ export class Windows {
 					: Math.round((remainingTokens / contextWindow) * 1000) / 10,
 		};
 	}
-	reminder(ctx: ExtensionContext): CustomMessageEntryDraft | undefined {
+	reminder(
+		ctx: ExtensionContext,
+		taskBoundaryReminder = 0,
+		checkpointReminder = true,
+	): CustomMessageEntryDraft | undefined {
 		const { remainingTokens, contextWindow, remainingPercent } =
 			this.remaining(ctx);
-		if (!this.current || remainingTokens === undefined) return;
-		const used = 100 * (1 - remainingTokens / contextWindow);
-		const kind = used >= 90 ? "urgent" : used >= 85 ? "reminder" : undefined;
-		if (!kind || this.reminders.has(`${this.current.currentWindowId}:${kind}`))
+		if (
+			!this.current ||
+			remainingTokens === undefined ||
+			remainingPercent === undefined
+		)
 			return;
-		this.reminders.add(`${this.current.currentWindowId}:reminder`);
+		const used = 100 * (1 - remainingTokens / contextWindow);
+		let kind: WindowDetails["kind"] | undefined = checkpointReminder
+			? used >= 90
+				? "urgent"
+				: used >= 85
+					? "reminder"
+					: undefined
+			: undefined;
+		if (kind && this.reminders.has(`${this.current.currentWindowId}:${kind}`))
+			kind = undefined;
+		if (
+			!kind &&
+			taskBoundaryReminder &&
+			!this.reminders.has(`${this.current.currentWindowId}:task-boundary`) &&
+			taskBoundaryEligible(ctx, taskBoundaryReminder)
+		)
+			kind = "task-boundary";
+		if (!kind) return;
+		this.reminders.add(`${this.current.currentWindowId}:${kind}`);
 		if (kind === "urgent")
-			this.reminders.add(`${this.current.currentWindowId}:urgent`);
+			this.reminders.add(`${this.current.currentWindowId}:reminder`);
 		return {
 			type: "custom_message",
 			customType: WINDOW_MESSAGE,
-			content: `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% remaining. Checkpoint the active request, state and known history IDs in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
+			content:
+				kind === "task-boundary"
+					? renderTaskBoundaryReminder(remainingPercent)
+					: `<context_window_reminder>\n${kind === "urgent" ? "Urgent: " : ""}${remainingPercent}% remaining. Checkpoint the active request, state and known history IDs in notes, then call new_context ${kind === "urgent" ? "now, before other work" : "before continuing work"}.\n</context_window_reminder>`,
 			display: true,
 			details: {
 				protocol: 1,