@astrosheep/pi-context 0.11.0 → 0.12.0

package/README.md

@@ -71,7 +71,7 @@ The nine Codex History/Notes actions are flattened because Pi tools have one glo
 
 `history_*` and paged `notes_*` read/search results share a **32 KiB (32 * 1024 UTF-8 bytes) per-result budget**. List/search tools return whole items only and include `next_offset` (an integer cursor, or `null` when exhausted); pass that cursor back with the same parameters to continue. `history_read_item` defaults to `limit_chars: 12000`, accepts at most 50000, and returns `total_chars` plus `next_offset_chars` when more content remains. `notes_read_file` returns whole lines only, includes `total_lines`, and uses `next_start_line` for a bounded continuation. When one indivisible unit is larger than the whole budget (a single note line, search match, or history item), it is returned middle-truncated — head and tail joined by a `…[truncated N chars]…` marker, mirroring Codex's `truncate_middle` — instead of being dropped, so a page is never empty and its cursor always advances. `max_chars_per_item` limits Unicode code points including the truncation ellipsis (`…`). The 32 KiB choice matches Aider's default and Claude Code's roughly 30k-character limit while keeping worst-case CJK output (about 11k tokens) below Pi's default `reserveTokens` of 16384.
 
-`notes_*` stores operation entries in the same append-only Pi session under `pi-context/note`. They are session-scoped, survive JSONL reload, never enter provider context, and use safe relative virtual paths only (no absolute paths, `..`, `.`, empty components, or backslashes). Searches are literal and case-sensitive. `notes_read_file` accepts inclusive 1-based line ranges; negative line numbers count from the last line. `notes_read_file` success results and every matched file object from `notes_search_contents` also carry `created_at` and `updated_at`, the same fields `notes_list_files_by_prefix` returns. All note timestamps are local-time ISO 8601 strings with an explicit UTC offset (for example `2026-09-15T17:31:45.392+08:00`; a UTC host renders `+00:00`, never `Z`), while the persisted `NoteFile`/`NoteOperation` metadata keeps plain epoch milliseconds. Error results carry no timestamps. Writes are capped at 1,000,000 UTF-8 bytes. `notes_write_file` and `notes_append_to_file` declare `executionMode: "sequential"` (the Pi equivalent of Codex's `supports_parallel_tool_calls = false`), so a tool batch containing either runs its calls one at a time and note read-modify-write cannot race with itself.
+`notes_*` stores operation entries in the same append-only Pi session under `pi-context/note`. They are session-scoped, survive JSONL reload, never enter provider context, and use safe relative virtual paths only (no absolute paths, `..`, `.`, empty components, or backslashes). Searches are literal and case-sensitive. `notes_read_file` accepts inclusive 1-based line ranges; negative line numbers count from the last line. Staleness is explicit and never inferred from timestamps. `notes_write_file` and `notes_append_to_file` accept an optional `mark_stale` boolean, and `notes_list_files_by_prefix` reports each file's `stale` flag. Stale notes leave the boot notes index — which omits itself once no fresh note remains — but stay listed, readable, and searchable. Each call must carry `text`, `mark_stale`, or both: `mark_stale: true` alone flags a note without touching its content, `mark_stale: false` alone clears the flag without touching content, and either call may carry `text` too — so final content can be written and marked stale in one call, and a closing log line can be appended and marked stale in one call. Carrying `text` without `mark_stale` revives a stale note, and marking a path that does not exist is an error. `notes_read_file` success results and every matched file object from `notes_search_contents` also carry `created_at` and `updated_at`, the same fields `notes_list_files_by_prefix` returns. All note timestamps are local-time ISO 8601 strings with an explicit UTC offset (for example `2026-09-15T17:31:45.392+08:00`; a UTC host renders `+00:00`, never `Z`), while the persisted `NoteFile`/`NoteOperation` metadata keeps plain epoch milliseconds. Error results carry no timestamps. Writes are capped at 1,000,000 UTF-8 bytes. `notes_write_file` and `notes_append_to_file` declare `executionMode: "sequential"` (the Pi equivalent of Codex's `supports_parallel_tool_calls = false`), so a tool batch containing either runs its calls one at a time and note read-modify-write cannot race with itself.
 
 Unlike Codex, the history tools do not advertise `agent_name`: Pi has no cross-agent session routing, so the parameter is omitted from the schemas entirely (strict `additionalProperties: false` still rejects it) instead of costing schema tokens on every request.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/src/note-tools.ts

@@ -23,7 +23,7 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			const key = params.file_order_by ?? "name";
 			files.sort(([aPath, a], [bPath, b]) => key === "name" ? aPath.localeCompare(bPath) : (key === "created_at" ? a.createdAt - b.createdAt : a.updatedAt - b.updatedAt));
 			if (params.file_order === "descending") files.reverse();
-			const listed = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
+			const listed = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), stale: file.stale, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
 			return output(page(listed, params.offset ?? 0, "files", params.max_results, (file, fits) => ({ ...file, path: middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate })) })));
 		},
 	}));
@@ -81,21 +81,30 @@ export function registerNoteTools(pi: ExtensionAPI) {
 		pi.registerTool(defineTool({
 			name,
 			label: name === "notes_append_to_file" ? "Notes append" : "Notes write",
-			description: name === "notes_append_to_file" ? "Append exact text to a persistent virtual note file." : "Create or replace a persistent virtual note file.",
-			parameters: Type.Object({ text: Type.String(), path: Type.String() }, { additionalProperties: false }),
+			description: name === "notes_append_to_file"
+				? "Append exact text to a persistent virtual note file. Appending suits chronological logs; for current-state notes, replace the whole file with notes_write_file instead. Accepts the same mark_stale flag to close a note."
+				: "Create or replace a persistent virtual note file. Keep notes small and split by topic; replace outdated notes whole. With mark_stale: true, flag the note as stale instead — optionally writing its final content in the same call: stale notes leave the boot index but stay readable and searchable, and rewriting revives them.",
+			parameters: Type.Object({ text: Type.Optional(Type.String()), path: Type.String(), mark_stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
 			// Codex sets supports_parallel_tool_calls = false on notes.write_file/append_to_file.
 			// Pi's per-tool equivalent is executionMode "sequential": a batch containing either
 			// tool runs its calls one at a time, so note read-modify-write cannot race.
 			executionMode: "sequential",
 			async execute(_id, params, _signal, _update, ctx) {
 				const path = assertVirtualPath(params.path);
+				const hasText = params.text !== undefined;
+				const hasStale = params.mark_stale !== undefined;
+				if (!hasText && !hasStale) return output({ error: "provide text, mark_stale, or both", path });
 				const old = notesFromSession(ctx).get(path);
-				const next = op === "append" ? `${old?.text ?? ""}${params.text}` : params.text;
+				if (!hasText && !old) return output({ error: "note file not found", path });
+				const next = hasText ? (op === "append" ? `${old?.text ?? ""}${params.text}` : params.text as string) : old!.text;
 				const bytes = Buffer.byteLength(next, "utf8");
-				if (bytes > MAX_NOTE_BYTES) return output({ error: `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes`, path, size_bytes: bytes });
+				if (hasText && bytes > MAX_NOTE_BYTES) return output({ error: `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes`, path, size_bytes: bytes });
 				const now = Date.now();
-				saveNote({ op, path, text: params.text, createdAt: old?.createdAt ?? now, updatedAt: now });
-				return output({ path, size_bytes: bytes, operation: op });
+				const operation: NoteOperation = { op, path, createdAt: old?.createdAt ?? now, updatedAt: now };
+				if (hasText) operation.text = params.text;
+				if (hasStale) operation.stale = params.mark_stale;
+				saveNote(operation);
+				return output({ path, size_bytes: bytes, operation: op, stale: hasStale ? params.mark_stale : false });
 			},
 		}));
 	}

package/src/notes.ts

@@ -1,11 +1,14 @@
 import type { SessionReader } from "./session-reader.js";
 import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
 
-export type NoteFile = { text: string; createdAt: number; updatedAt: number };
+export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
 export type NoteOperation = {
 	op: "write" | "append";
 	path: string;
-	text: string;
+	// Both are optional on the wire so mark-only and explicit-revive operations replay:
+	// at least one of text/stale is present, enforced by the note tools and isNoteOperation.
+	text?: string;
+	stale?: boolean;
 	createdAt: number;
 	updatedAt: number;
 };
@@ -29,7 +32,9 @@ function isNoteOperation(data: unknown): data is NoteOperation {
 	return (
 		(op.op === "write" || op.op === "append") &&
 		typeof op.path === "string" &&
-		typeof op.text === "string" &&
+		(op.text === undefined || typeof op.text === "string") &&
+		(op.stale === undefined || typeof op.stale === "boolean") &&
+		(op.text !== undefined || op.stale !== undefined) &&
 		typeof op.createdAt === "number" && Number.isFinite(new Date(op.createdAt).getTime()) &&
 		typeof op.updatedAt === "number" && Number.isFinite(new Date(op.updatedAt).getTime())
 	);
@@ -46,10 +51,14 @@ export function notesFromSession(ctx: SessionReader): Map<string, NoteFile> {
 			continue;
 		}
 		const previous = files.get(op.path);
-		const text = op.op === "append" ? `${previous?.text ?? ""}${op.text}` : op.text;
-		if (Buffer.byteLength(text, "utf8") <= MAX_NOTE_BYTES) {
-			files.set(op.path, { text, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
-		}
+		const hasText = op.text !== undefined;
+		// A mark-only operation needs an existing note to change; without one it is a no-op.
+		if (!hasText && !previous) continue;
+		const text = hasText ? (op.op === "append" ? `${previous?.text ?? ""}${op.text}` : op.text as string) : previous!.text;
+		if (Buffer.byteLength(text, "utf8") > MAX_NOTE_BYTES) continue;
+		// Carrying text revives unless the call also marks stale; a mark-only op keeps its flag.
+		const stale = hasText ? op.stale ?? false : op.stale ?? previous!.stale;
+		files.set(op.path, { text, stale, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
 	}
 	return files;
 }

package/src/prompts.ts

@@ -15,15 +15,16 @@ function identityBlock(agentName: string, firstWindowId: string, currentWindowId
 }
 
 /**
- * Recent-notes index: up to three most-recent notes. Each note shows its path, line count,
- * UTF-8 byte count and local ISO update time, followed by an indented inline preview: the
- * whole text when it fits in NOTE_PREVIEW_CHARS, otherwise its first NOTE_PREVIEW_HEAD_CHARS
- * and last NOTE_PREVIEW_TAIL_CHARS Unicode characters joined by an explicit ellipsis. The
- * two slices never overlap, so the preview never duplicates head content as tail content.
- * Empty when the session has no notes.
+ * Recent-notes index: up to three most-recent fresh (non-stale) notes. Each note shows its
+ * path, line count, UTF-8 byte count and local ISO update time, followed by an indented inline
+ * preview: the whole text when it fits in NOTE_PREVIEW_CHARS, otherwise its first
+ * NOTE_PREVIEW_HEAD_CHARS and last NOTE_PREVIEW_TAIL_CHARS Unicode characters joined by an
+ * explicit ellipsis. The two slices never overlap, so the preview never duplicates head content
+ * as tail content. Stale notes are excluded entirely; empty when no fresh notes remain.
  */
 function notesIndex(ctx: ExtensionContext): string {
 	const recentNotes = [...notesFromSession(ctx)]
+		.filter(([, file]) => !file.stale)
 		.sort((a, b) => b[1].updatedAt - a[1].updatedAt)
 		.slice(0, 3);
 	if (recentNotes.length === 0) return "";