@howaboua/pi-notes-compaction 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @howaboua/pi-notes-compaction
 
+## 0.0.4
+
+- Fixed note queries and manual context rollover with Codex Conversion.
+
+  - Restored negative line ranges, default limits, result ordering, metadata and complete read and search content. Help now shows concrete call syntax, and invalid arguments are reported before execution.
+  - `/compact` now honours the Normal compaction setting. With it off, Notes Compaction reuses fresh saved notes or requests a checkpoint, then opens a new context window without starting a continuation turn.
+
+## 0.0.3
+
+- Fixed shared agent startup after package updates when the startup changelog is present.
+
 ## 0.0.2
 
 - Added a `/notes` settings panel for normal compaction, idle rollover, continuity status and confirmed pruning, replacing the subcommands and JSON status output.

package/PCC-INTEGRATION.md

@@ -35,7 +35,7 @@ Required boundaries in the current source:
 
 - `context-management/tools.ts` and `extension/tools.ts`: replace the four tools through the registration callback. Active-tool and schema rewrites must preserve delegated definitions. Do not reinstall legacy routers on model changes or settings changes.
 - `extension/session-lifecycle.ts` and `extension/turn-lifecycle.ts`: skip legacy notes/window initialization, input holding, checkpoint admission, note freshness, reminders, settlement records and continuation scheduling. Leave PCC's prompt preparation, runtime synchronization, Notebook status, voice, quota and provider lifecycle active.
-- `extension/compaction-lifecycle.ts`: skip only legacy `contextWindows.prepareCompaction` and notes checkpoint overrides. When this extension allows normal compaction, run the unchanged installed PCC normal-compaction path. Overflow stays in the same window. Notebook checkpointing, native compaction, replay, transport reset and presentation remain PCC-owned.
+- `extension/compaction-lifecycle.ts`: consult `owner.allowsCompaction(reason)` before any compaction work. When false, return without work so the owner's hook can cancel and handle notes-only rollover, regardless of extension order. Skip legacy `contextWindows.prepareCompaction` and notes checkpoint overrides. When this extension allows normal compaction, run the unchanged installed PCC normal-compaction path. Overflow stays in the same window. Notebook checkpointing, native compaction, replay, transport reset and presentation remain PCC-owned.
 - `context-management/window-manager.ts`, `window-request.ts` and native replay serializers: use `owner.identity(ctx)` and `owner.projectBranch(entries)` for the active window and retirement boundary. Preserve PCC request metadata and zero-based generation semantics. Do not recreate remote history-ingest requirements for local notes.
 - PCC message preparation and `adapter/developer-messages.ts`: preserve `notes-compaction:window:v1` and `notes-compaction:checkpoint:v1` custom messages on every model. Compatible Responses routes may promote them to developer messages. Ordinary Pi conversion must retain them on other routes. Use `owner.projectMessages(messages)` before native replay/prewarm, without overwriting another extension's preparation.
 - Settings UI: show notes continuity as externally managed. Preserve old PCC values for sessions without the external extension. Do not add another compaction setting to this extension.

package/README.md

@@ -20,7 +20,9 @@ The agent keeps the familiar `notes`, `history`, `new_context` and `get_context_
 
 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.
 
-Reminders arrive at 85% and 90% context use. `/compact` requests a notes checkpoint and opens a new window only after a completed run with fresh saved notes. Abort, errors and failed writes retain the old context. Overflow recovery still uses Pi's normal compaction.
+Reminders arrive at 85% and 90% context use. With normal compaction off, `/compact` opens a fresh window immediately if the latest completed turn saved fresh notes. Otherwise it requests a checkpoint first. The new window waits for your next prompt; it does not start a continuation turn. Abort, errors and failed writes retain the old context. Overflow recovery still uses Pi's normal compaction.
+
+Pi rejects `/compact` when there is too little history to prepare compaction, before extensions run. In that case, the agent can still use `new_context`.
 
 Idle rollover is off by default. Choose 5, 15, 25 or 55 minutes in `/notes`. After that interval, the next input waits for rollover only if the latest completed turn saved fresh notes. Otherwise it proceeds in the current window without requesting a checkpoint. These intervals are user preferences, not provider cache-expiry guarantees. Held input retains its original text, attachments and SDK options. A failed rollover keeps input pending. Submit another prompt to retry, or reload to cancel it.
 
@@ -28,7 +30,7 @@ Idle rollover is off by default. Choose 5, 15, 25 or 55 minutes in `/notes`. Aft
 
 `/notes` opens the settings panel in interactive Pi. It shows continuity status, storage counts and remote capabilities. Changes save immediately.
 
-- **Normal compaction** includes the installed Pi or PCC compaction flow on `new_context`. Off keeps notes-only rollover, the default.
+- **Normal compaction** uses the installed Pi or PCC compaction flow for `/compact` and `new_context`. Off keeps notes-only rollover, the default.
 - **Idle rollover** selects the interval or disables it.
 - **Prune missing sessions** removes records for missing session files after confirmation. Unknown paths, permission errors and the active session are retained.
 

package/package.json

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

package/src/bridge.ts

@@ -3,6 +3,7 @@ import type {
 	AgentToolResult,
 	ExtensionAPI,
 	ExtensionContext,
+	SessionBeforeCompactEvent,
 	SessionEntry,
 	ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
@@ -68,6 +69,8 @@ export interface NotesOwner {
 	identity(ctx: ExtensionContext): WindowIdentity | undefined;
 	projectMessages(messages: readonly AgentMessage[]): AgentMessage[];
 	projectBranch(entries: readonly SessionEntry[]): SessionEntry[];
+	/** Consult before compaction work; the owner's hook performs notes-only rollover. */
+	allowsCompaction?(reason: SessionBeforeCompactEvent["reason"]): boolean;
 	canBind?(ctx: ExtensionContext): boolean;
 	snapshotNotes?(
 		entries: readonly SessionEntry[],

package/src/index.ts

@@ -43,10 +43,17 @@ export default function notesCompaction(pi: ExtensionAPI): void {
 			lifecycle.windows.current ? { ...lifecycle.windows.current } : undefined,
 		projectMessages: (messages) => lifecycle.windows.projectMessages(messages),
 		projectBranch: (entries) => lifecycle.windows.projectBranch(entries),
+		allowsCompaction: (reason) => lifecycle.allowsCompaction(reason),
 		canBind: (ctx) =>
 			lifecycle.active &&
 			ctx.isIdle() &&
 			ctx.sessionManager.getEntries().every((entry) => {
+				// The first startup after an update records a UI-only changelog.
+				if (
+					entry.type === "custom" &&
+					entry.customType === "@howaboua/pi-stuff/changelog"
+				)
+					return true;
 				// Herdr activation persists its empty registry before first task delivery.
 				if (
 					entry.type === "custom" &&

package/src/lifecycle.ts

@@ -357,11 +357,7 @@ export class NotesLifecycle {
 		event: SessionBeforeCompactEvent,
 		ctx: ExtensionContext,
 	): { cancel: true } | undefined {
-		if (
-			this.normalCompaction ||
-			this.rollover?.phase === "compacting" ||
-			event.reason === "overflow"
-		) {
+		if (this.allowsCompaction(event.reason)) {
 			// PCC owns preparation when bridged, including native checkpoint routes.
 			if (this.bridge) return;
 			try {
@@ -435,6 +431,13 @@ export class NotesLifecycle {
 			};
 		return { cancel: true };
 	}
+	allowsCompaction(reason: SessionBeforeCompactEvent["reason"]): boolean {
+		return (
+			this.normalCompaction ||
+			this.rollover?.phase === "compacting" ||
+			reason === "overflow"
+		);
+	}
 	async compactFailed(
 		event: SessionCompactFailedEvent,
 		ctx: ExtensionContext,
@@ -450,7 +453,7 @@ export class NotesLifecycle {
 		)
 			return;
 		if (!pending.instructions?.trim() && this.fresh(ctx))
-			await this.roll(ctx, true);
+			await this.roll(ctx, false);
 		else this.startCheckpoint(ctx, pending.instructions);
 	}
 	async settled(
@@ -517,7 +520,7 @@ export class NotesLifecycle {
 				);
 				return;
 			}
-			await this.roll(ctx, true);
+			await this.roll(ctx, false);
 			return;
 		}
 		if (this.held?.phase === "draining") {

package/src/notes.ts

@@ -216,25 +216,34 @@ export function exportNotesSnapshot(
 }
 
 function canonicalPath(path: unknown, agent: string, required = true): string {
-	if (typeof path !== "string" || !path.trim()) {
-		if (required) throw new Error("Supply a note path");
+	if (path === undefined || path === null || path === "") {
+		if (required) throw new Error("Note file path is required");
 		return "";
 	}
+	if (typeof path !== "string")
+		throw new Error(
+			required ? "Note file path is required" : "Note prefix must be a string",
+		);
 	const root = `${agent}/notes`;
 	let value = path;
-	if (value === root) value = "";
-	else if (value.startsWith(`${root}/`)) value = value.slice(root.length + 1);
+	if (value === root) {
+		if (required)
+			throw new Error("Absolute note paths must use <agent>/notes/<path>");
+		value = "";
+	} else if (value.startsWith(`${root}/`)) value = value.slice(root.length + 1);
 	else if (value.startsWith("/"))
 		throw new Error(
 			"That agent's notes are not available here. Use a relative path for this agent.",
 		);
 	if (
 		(required && !value) ||
-		value.split("/").some((part) => part === ".." || part === ".") ||
-		/[\0\r\n]/.test(value)
+		(value !== "" &&
+			value.split("/").some((part) => !part || part === ".." || part === "."))
 	)
 		throw new Error(
-			"Use a virtual note path without dot segments or control characters",
+			required
+				? "Note paths cannot contain empty, . or .. components"
+				: "Note prefixes cannot contain empty, . or .. components",
 		);
 	return value;
 }
@@ -244,11 +253,8 @@ export function normalizeNoteParams(
 	agent: string,
 ): Record<string, unknown> {
 	const result = { ...params };
-	const needsPath = ["read_file", "write_file", "append_to_file"].includes(
-		String(params["action"]),
-	);
 	for (const field of ["path", "prefix", "path_prefix"])
-		if (field in params || field !== "path" || needsPath)
+		if (field in params)
 			result[field] = canonicalPath(params[field], agent, field === "path");
 	return result;
 }
@@ -285,12 +291,13 @@ export function useNotes(
 	if (action === "write_file" || action === "append_to_file") {
 		const path = params["path"] as string;
 		const text = params["text"];
-		if (typeof text !== "string") throw new Error("Supply note text");
+		if (typeof text !== "string")
+			throw new Error(`notes ${action} requires text`);
 		const previous = notes.get(path);
 		const next =
 			action === "append_to_file" ? (previous?.text ?? "") + text : text;
 		if (Buffer.byteLength(next) > 1_000_000)
-			throw new Error("Note exceeds 1 MB. Split it into separate paths.");
+			throw new Error("Note file exceeds the 1,000,000-byte limit");
 		const now = Date.now();
 		// Append never pretends to decode a remote base. The remote fragment remains separate.
 		const mode =
@@ -324,113 +331,101 @@ export function useNotes(
 			);
 		}
 		return {
-			path: `${root}${path}`,
-			chars: next.length,
-			operation:
-				mode === "append" ? "local_append_overlay" : "local_replacement",
+			source: "pi-session",
+			file: noteMetadata(revision, root),
 		};
 	}
+
 	if (action === "read_file") {
 		const path = params["path"] as string;
 		const note = notes.get(path);
-		if (!note) return { path: `${root}${path}`, file: null };
+		if (!note) return { source: "pi-session", file: null };
 		const lines = note.text.split("\n");
-		const start = integer(params["start_line"], 1, lines.length + 1);
-		const stop = integer(params["stop_line"], lines.length, lines.length);
-		let text = "";
-		let next = start;
-		while (next <= stop) {
-			const line = lines[next - 1] ?? "";
-			if (text.length + line.length > 32_000) {
-				if (!text)
-					throw new Error(
-						"This note line exceeds 32000 characters. Rewrite it as shorter lines to read it.",
-					);
-				break;
-			}
-			text += `${next > start ? "\n" : ""}${line}`;
-			next++;
-		}
+		const start = lineIndex(params["start_line"], lines.length, 0);
+		const stop = lineIndex(params["stop_line"], lines.length, lines.length - 1);
 		return {
-			path: `${root}${path}`,
-			text,
-			start_line: start,
-			total_lines: lines.length,
-			...(next <= stop ? { next_start_line: next } : {}),
-			operation:
-				note.mode === "replace" ? "local_replacement" : "local_append_overlay",
+			source: "pi-session",
+			file: {
+				...noteMetadata(note, root),
+				content: start <= stop ? lines.slice(start, stop + 1).join("\n") : "",
+				start_line: start + 1,
+				stop_line: Math.max(start, stop) + 1,
+				total_lines: lines.length,
+			},
 		};
 	}
 	if (action === "list_files_by_prefix") {
-		let files = [...notes.values()].filter((note) =>
-			note.path.startsWith(String(params["prefix"] ?? "")),
-		);
 		const by = params["file_order_by"];
-		files.sort((a, b) =>
-			by === "created_at"
-				? a.createdAt - b.createdAt
-				: by === "updated_at"
-					? a.updatedAt - b.updatedAt
-					: a.path.localeCompare(b.path),
-		);
-		if (params["file_order"] === "descending") files.reverse();
-		const maximum = integer(params["max_results"], 100, 100);
-		return {
-			files: files.slice(0, maximum).map((note) => ({
-				path: `${root}${note.path}`,
-				chars: note.text.length,
-				updated_at: note.updatedAt,
-			})),
-			truncated: files.length > maximum,
-		};
+		const direction = params["file_order"] === "descending" ? -1 : 1;
+		const files = [...notes.values()]
+			.filter((note) => note.path.startsWith(String(params["prefix"] ?? "")))
+			.sort(
+				(a, b) =>
+					(by === "created_at"
+						? a.createdAt - b.createdAt
+						: by === "updated_at"
+							? a.updatedAt - b.updatedAt
+							: a.path.localeCompare(b.path)) * direction,
+			)
+			.slice(0, integer(params["max_results"], 20, 100))
+			.map((note) => noteMetadata(note, root));
+		return { source: "pi-session", files };
 	}
-	if (
-		action !== "search_contents" ||
-		typeof params["query"] !== "string" ||
-		!params["query"]
-	)
-		throw new Error("Supply a nonempty search query");
+	if (action !== "search_contents")
+		throw new Error("notes requires a supported action");
+	const query = params["query"];
+	if (typeof query !== "string" || !query)
+		throw new Error("notes search_contents requires query");
 	const files = [...notes.values()].filter((note) =>
 		note.path.startsWith(String(params["path_prefix"] ?? "")),
 	);
-	if (params["recent_file_first"] === true)
-		files.sort((a, b) => b.updatedAt - a.updatedAt);
-	const found: {
-		path: string;
-		matches: { line: number; text: string }[];
-		truncated: boolean;
-	}[] = [];
-	let chars = 0;
-	let truncated = false;
+	files.sort(
+		params["recent_file_first"] === true
+			? (a, b) => b.createdAt - a.createdAt
+			: (a, b) => a.path.localeCompare(b.path),
+	);
+	const found: Record<string, unknown>[] = [];
 	for (const note of files) {
-		const all = note.text
+		const matches = note.text
 			.split("\n")
-			.flatMap((line, i) =>
-				line.includes(params["query"] as string)
-					? [{ line: i + 1, text: line.slice(0, 1000) }]
-					: [],
-			);
-		if (!all.length) continue;
-		const matches = all.slice(
-			0,
-			integer(params["max_matches_per_file"], 10, 100),
-		);
-		const size = JSON.stringify(matches).length;
-		if (
-			found.length >= integer(params["max_files"], 20, 100) ||
-			chars + size > 32_000
-		) {
-			truncated = true;
-			break;
-		}
+			.map((line, index) => ({ line_number: index + 1, line }))
+			.filter(({ line }) => line.includes(query))
+			.slice(0, integer(params["max_matches_per_file"], 20, 100));
+		if (!matches.length) continue;
 		found.push({
 			path: `${root}${note.path}`,
 			matches,
-			truncated: matches.length < all.length,
+			operation:
+				note.mode === "replace" ? "local_replacement" : "local_append_overlay",
 		});
-		chars += size;
+		if (found.length >= integer(params["max_files"], 20, 100)) break;
 	}
-	return { files: found, truncated };
+	return { source: "pi-session", files: found };
+}
+
+function noteMetadata(
+	note: NoteRevision,
+	root: string,
+): Record<string, unknown> {
+	return {
+		operation:
+			note.mode === "replace" ? "local_replacement" : "local_append_overlay",
+		path: `${root}${note.path}`,
+		bytes: Buffer.byteLength(note.text, "utf8"),
+		created_at: new Date(note.createdAt).toISOString(),
+		updated_at: new Date(note.updatedAt).toISOString(),
+	};
+}
+
+function lineIndex(
+	value: unknown,
+	lineCount: number,
+	fallback: number,
+): number {
+	if (typeof value !== "number" || !Number.isInteger(value) || value === 0)
+		return fallback;
+	const index = value > 0 ? value - 1 : lineCount + value;
+	return Math.max(0, Math.min(index, Math.max(0, lineCount - 1)));
 }
 
 function integer(value: unknown, fallback: number, max: number): number {

package/src/settings-screen.ts

@@ -27,7 +27,7 @@ export async function openNotesSettings(
 							id: "compact",
 							label: "Normal compaction",
 							description:
-								"Include the installed Pi/PCC compaction flow on new_context. Off keeps notes-only rollover.",
+								"Use Pi/PCC compaction for /compact and new_context. Off uses notes-only rollover; /compact then waits for your next prompt.",
 							currentValue: settings.normalCompaction ? "on" : "off",
 							values: ["off", "on"],
 						},

package/src/tools.ts

@@ -6,6 +6,7 @@ import type {
 	ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { Check } from "typebox/value";
 import type {
 	CachedResponse,
 	LookupQuery,
@@ -44,16 +45,18 @@ export const NOTES_USAGE = "await tools.notes() // help";
 export const HISTORY_USAGE = "await tools.history() // help";
 const STRING = Type.Optional(Type.String());
 const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
+const NULLABLE_STRING = Type.Optional(Type.Union([Type.String(), Type.Null()]));
+const LINE = Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
 const NOTES_SCHEMA = Type.Object(
 	{
 		action: Type.Optional(StringEnum(NOTES_ACTIONS)),
 		path: STRING,
 		text: STRING,
-		prefix: STRING,
+		prefix: NULLABLE_STRING,
 		query: STRING,
-		path_prefix: STRING,
-		start_line: INTEGER,
-		stop_line: INTEGER,
+		path_prefix: NULLABLE_STRING,
+		start_line: LINE,
+		stop_line: LINE,
 		max_results: INTEGER,
 		max_files: INTEGER,
 		max_matches_per_file: INTEGER,
@@ -146,7 +149,32 @@ function relevant(
 	const key =
 		action === "search_contents" ? `search_${namespace}` : String(action);
 	const fields = FIELDS[key];
-	if (!fields) throw new Error("Unknown action");
+	if (!fields)
+		throw new Error(
+			namespace === "notes"
+				? "notes requires a supported action"
+				: "Unknown action",
+		);
+	if (namespace === "notes") {
+		for (const field of Object.keys(params))
+			if (field !== "action" && !fields.includes(field))
+				throw new Error(`notes ${String(action)} does not accept ${field}`);
+		if (
+			["read_file", "write_file", "append_to_file"].includes(String(action)) &&
+			(typeof params["path"] !== "string" || !params["path"])
+		)
+			throw new Error(`notes ${String(action)} requires path`);
+		if (
+			action === "search_contents" &&
+			(typeof params["query"] !== "string" || !params["query"])
+		)
+			throw new Error("notes search_contents requires query");
+		if (
+			["write_file", "append_to_file"].includes(String(action)) &&
+			typeof params["text"] !== "string"
+		)
+			throw new Error(`notes ${String(action)} requires text`);
+	}
 	return Object.fromEntries(
 		Object.entries(params).filter(
 			([key]) => key === "action" || fields.includes(key),
@@ -192,6 +220,16 @@ function discovery(
 							).join(" "),
 				]),
 			),
+			...(namespace === "notes"
+				? {
+						usage:
+							'await tools.notes({ action: "read_file", path: "checkpoint" })',
+						ranges:
+							"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",
+						defaults:
+							"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",
+					}
+				: {}),
 		});
 	}
 	return undefined;
@@ -484,15 +522,29 @@ export function createTools(
 			prepareArguments(args) {
 				if (args === undefined) return {};
 				if (!args || typeof args !== "object" || Array.isArray(args))
-					return args;
+					throw new Error(
+						'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"] === "list_files_by_prefix" &&
 					params["max_files"] !== undefined
 				) {
-					params["max_results"] ??= params["max_files"];
+					if (!("max_results" in params))
+						params["max_results"] = params["max_files"];
 					delete params["max_files"];
 				}
+				if (!discovery("notes", params)) relevant("notes", params);
+				for (const [field, value] of Object.entries(params)) {
+					const schema =
+						NOTES_SCHEMA.properties[
+							field as keyof typeof NOTES_SCHEMA.properties
+						];
+					if (!schema || !Check(schema, value))
+						throw new Error(
+							`Invalid notes ${field}; call tools.notes() for exact arguments`,
+						);
+				}
 				return params;
 			},
 			execute: (callId, input, signal, _update, ctx) =>