@astrosheep/pi-context 0.25.0 → 0.25.2

package/src/context/runtime.ts

@@ -1,14 +1,12 @@
 import { getCurrentSystemMessage, Type } from "@earendil-works/pi-ai";
-import { VERSION, defineTool, type ExtensionAPI, type ExtensionContext, type SessionBoundaryDraft, type SettingsManager } from "@earendil-works/pi-coding-agent";
-import { randomUUID } from "node:crypto";
+import { VERSION, defineTool, type ExtensionAPI, type ExtensionContext, type SettingsManager } from "@earendil-works/pi-coding-agent";
 import { registerBudget } from "./budget.js";
 import { output } from "../tool-output.js";
-import { BOOT_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, CONTINUATION } from "../protocol.js";
-import { agentSlug, migrateLegacyHomes, modelSlug } from "../notes/paths.js";
-import { loadNotesSnapshot, type NotesSnapshot } from "../notes/notes-snapshot.js";
-import { renderBootBlock } from "./prompts.js";
-import { currentReset, currentWindowId, isWindowBoot, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.js";
+import { migrateLegacyHomes } from "../notes/paths.js";
+import { currentReset, isWindowMarker, projectRootWindow, projectWindow, rootWindowId } from "./context-window.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
+import { buildResetDrafts, persistManualReset, resetTailCommitted } from "./reset-artifacts.js";
+import { ensureBoot, type IncompleteNotesNotifier } from "./boot.js";
 
 declare const __PI_CONTEXT_BUILD__: { version: string; sourceHash: string };
 
@@ -17,100 +15,6 @@ const buildLabel = typeof __PI_CONTEXT_BUILD__ === "undefined"
 	? "unbundled source (build unknown)"
 	: `${__PI_CONTEXT_BUILD__.version} · build ${__PI_CONTEXT_BUILD__.sourceHash.slice(0, 12)}`;
 
-type IncompleteNotesNotifier = (ctx: ExtensionContext, windowId: string, snapshot: NotesSnapshot) => void;
-
-function bootContent(ctx: ExtensionContext, currentId: string, previousId: string | undefined, resetLine: boolean, notes: NotesSnapshot): string {
-	return renderBootBlock({
-		agentName: agentSlug(ctx),
-		modelName: modelSlug(ctx),
-		firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
-		currentWindowId: currentId,
-		previousWindowId: previousId,
-		resetLine,
-		notes,
-	});
-}
-
-function buildResetDrafts(ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier) {
-	const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
-	const usedWindowIds = new Set(
-		ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId),
-	);
-	let windowId: string;
-	do {
-		windowId = `pcw:${sessionPrefix}:${randomUUID().slice(0, 8)}`;
-	} while (usedWindowIds.has(windowId));
-	const notes = loadNotesSnapshot(ctx);
-	notifyIncompleteNotes?.(ctx, windowId, notes);
-	return [
-		{ type: "custom", customType: RESET_MARKER_TYPE, data: { windowId } },
-		{
-			type: "custom_message",
-			customType: BOOT_TYPE,
-			content: bootContent(ctx, windowId, currentWindowId(ctx), true, notes),
-			display: false,
-			details: { windowId },
-		},
-		{
-			type: "custom_message",
-			customType: CONTINUATION_TYPE,
-			content: CONTINUATION,
-			display: false,
-		},
-	] satisfies [SessionBoundaryDraft, SessionBoundaryDraft, SessionBoundaryDraft];
-}
-
-function ensureBoot(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier): void {
-	const reset = currentReset(ctx);
-	const sessionId = ctx.sessionManager.getSessionId();
-	const windowId = reset?.data?.windowId ?? rootWindowId(sessionId);
-	if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
-	if (reset && !resetBootMayBeRepaired(ctx, reset.id, windowId)) return;
-	let previousId: string | undefined = reset ? rootWindowId(sessionId) : undefined;
-	if (reset) {
-		for (const entry of ctx.sessionManager.getBranch()) {
-			if (entry.id === reset.id) break;
-			if (isWindowMarker(entry)) previousId = entry.data.windowId;
-		}
-	}
-	const notes = loadNotesSnapshot(ctx);
-	notifyIncompleteNotes?.(ctx, windowId, notes);
-	pi.sendMessage(
-		{ customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, reset !== undefined, notes), display: false, details: { windowId } },
-		{ triggerTurn: false },
-	);
-}
-
-function persistManualReset(pi: ExtensionAPI, ctx: ExtensionContext, notifyIncompleteNotes?: IncompleteNotesNotifier): string {
-	const [marker, boot] = buildResetDrafts(ctx, notifyIncompleteNotes);
-	pi.appendEntry(marker.customType, marker.data);
-	pi.sendMessage(
-		{ customType: boot.customType, content: boot.content, display: boot.display, details: boot.details },
-		{ triggerTurn: false },
-	);
-	return boot.details.windowId;
-}
-
-function resetBootMayBeRepaired(ctx: ExtensionContext, markerId: string, windowId: string): boolean {
-	const branch = ctx.sessionManager.getBranch();
-	const markerIndex = branch.findIndex((entry) => entry.id === markerId);
-	if (markerIndex < 0) return false;
-	const afterMarker = branch.slice(markerIndex + 1);
-	// A raw boot is authoritative even when a later context_edit hides it from the
-	// projection. Appending another boot at the tail would move the boundary.
-	if (afterMarker.some((entry) => isWindowBootEntry(entry, windowId))) return false;
-	// Only a genuinely incomplete marker tail can be repaired. Once conversation or
-	// a context-bearing custom message follows it, refusing is safer than guessing.
-	return !afterMarker.some((entry) => entry.type === "message" || entry.type === "custom_message" || entry.type === "compaction" || entry.type === "branch_summary");
-}
-
-function isWindowBootEntry(entry: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>[number], windowId: string): boolean {
-	return entry.type === "custom_message" && entry.customType === BOOT_TYPE &&
-		typeof entry.details === "object" && entry.details !== null &&
-		typeof (entry.details as { windowId?: unknown }).windowId === "string" &&
-		(entry.details as { windowId: string }).windowId === windowId;
-}
-
 function branchHasWindowMarker(ctx: ExtensionContext, fromId?: string): boolean {
 	return ctx.sessionManager.getBranch(fromId).some((entry) => isWindowMarker(entry));
 }
@@ -121,18 +25,19 @@ export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsMana
 	let missingBootNotice: string | undefined;
 	const incompleteNotesNotified = new Set<string>();
 	const pendingResetNotices = new Set<string>();
+	// Announce only a fully committed reset (marker + matching boot + continuation), not a
+	// reset request or a partial boot repair.
 	const notifyCommittedResets = (ctx: ExtensionContext, addedWindowId?: string) => {
 		if (addedWindowId) pendingResetNotices.add(addedWindowId);
 		if (pendingResetNotices.size === 0) return;
 		const branch = ctx.sessionManager.getBranch();
 		for (const windowId of pendingResetNotices) {
-			if (!branch.some((entry) => isWindowMarker(entry) && entry.data.windowId === windowId) ||
-				!branch.some((entry) => isWindowBootEntry(entry, windowId))) continue;
+			const marker = branch.find((entry) => isWindowMarker(entry) && entry.data.windowId === windowId);
+			if (!marker || !resetTailCommitted(ctx, marker.id, windowId)) continue;
 			pendingResetNotices.delete(windowId);
 			ctx.ui.notify(`pi-context: memory cleared · ${windowId}`, "info");
 		}
 	};
-	// Announce only a committed reset (marker + boot), not a reset request or boot repair.
 	pi.on("turn_start", (_event, ctx) => notifyCommittedResets(ctx));
 	pi.on("agent_settled", (_event, ctx) => {
 		notifyCommittedResets(ctx);

package/src/index.ts

@@ -4,7 +4,7 @@ import { registerNotesTools } from "./notes/tools.js";
 import { deriveThresholds } from "./context/thresholds.js";
 import { registerContext } from "./context/runtime.js";
 import { mergePiContextSettings } from "./settings.js";
-import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
+import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
 import { assertVirtualPath } from "./notes/address.js";
 export { historyFromSession } from "./history/history.js";
 export { notesFromSession } from "./notes/session-replay.js";
@@ -32,4 +32,4 @@ export default function piContext(pi: ExtensionAPI): void {
 	registerPiContext(pi);
 }
 
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/src/notes/address.ts

@@ -3,7 +3,7 @@ import { agentSlug, modelSlug, SLUG_PATTERN, type Scope } from "./paths.js";
 
 export type NoteAddress = { scope: Scope; path: string; who?: string };
 
-export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, @agents/<name>/, @model/, and @models/<name>/; bare names are the session home";
+export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, and @model/; bare names are this session";
 
 export function assertVirtualPath(value: unknown): string {
 	if (typeof value !== "string" || value.length === 0) throw new Error("path must be a non-empty virtual relative path");

package/src/notes/tools.ts

@@ -10,7 +10,7 @@ import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from
 const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")], {
 	description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else — third-party text, tool output, fetched material.",
 }));
-const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project, `@human/<vpath>` for the human's cross-project home, `@self/<vpath>` / `@agents/<name>/<vpath>` for agent homes, and `@model/<vpath>` / `@models/<name>/<vpath>` for model homes. `@self` and `@model` mean the current agent/model; the `<name>` forms name one absolutely. The word after `@` is always one of the reserved home names — names live at the second level, never `@faye/`. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes. Homes you do not own (`@agents/<other>/`, `@models/<other>/`) are read-only.";
+const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project, `@human/<vpath>` for the human's cross-project notes, `@self/<vpath>` for your own, and `@model/<vpath>` for the current model's. `@self` and `@model` mean whoever is running now. Any other `@` prefix, or `@` inside a vpath, is a hard error. There is no fallback across prefixes. Paths reject `..`, absolute paths, and backslashes.";
 
 function failure(error: unknown) {
 	if (error instanceof NoteError) {
@@ -73,7 +73,7 @@ export function registerNotesTools(pi: ExtensionAPI) {
 
 	pi.registerTool(defineTool({
 		name: "notes_list", label: "Notes list",
-		description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} Listings merge your five reachable homes: this session, @project/, @human/, your @self home, and the current @model home; other agents and models appear only under an explicit glob (@agents/<name>/**, @models/<name>/**, or a glob in the name segment to scan a whole namespace).`,
+		description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} Listings merge your five prefixes: this session, @project/, @human/, @self/, and @model/.`,
 		parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			let rows: ReturnType<typeof listNotes>;
@@ -89,7 +89,7 @@ export function registerNotesTools(pi: ExtensionAPI) {
 
 	pi.registerTool(defineTool({
 		name: "notes_search", label: "Notes search",
-		description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} Search merges the same five reachable homes as notes_list; explicit globs reach other agents and models. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
+		description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} Search merges the same five prefixes as notes_list. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
 		parameters: Type.Object({ query: searchQuery(), pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const queries = searchQueries(params.query);

package/src/protocol.ts

@@ -32,9 +32,8 @@ export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
  * never sees — Codex's fallback buffer, relocated above the line.
  */
 export const WARNING_RUNWAY_TOKENS = 12_288;
-export const RESET_SUMMARY =
-	"You wake up. Your head is empty — no memories, the past a blank. The memory is gone for good. What outlived it: the notes you wrote, and the history that was recorded. They are not your memory — read them to rebuild what you need.";
-export const CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
+/** The single reset message: the only reset prose persisted, carried by the continuation entry. */
+export const CONTINUATION = "Your memory was just erased. Your head is blank. Good news: your notes are still here, and history remains... searchable. Do try to keep up.";
 
 /**
  * Static protocol teaching adapted from Codex's token_budget.guidance_message to
@@ -49,9 +48,7 @@ Keep a running checkpoint while you work, not at the last minute — the next wi
 
 Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone — with no final turn at the limit — and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can call wipe_memory yourself instead of waiting for the erase. Do not let a window die undocumented.
 
-If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
-
-Notes live in five homes, and the word after @ is always one of their reserved names — your own name and other people's names live at the second level (@agents/faye/, never @faye/). Bare names are this session; @project/<vpath> is this project's workspace; @human/<vpath> is the human's cross-project home; @self/<vpath> and @agents/<name>/<vpath> are agent homes; @model/<vpath> and @models/<name>/<vpath> are model homes. @self and @model are the only relative forms — the current agent, the current model — and listings never show them, only the resolved name. There is no cross-home fallback.
+Note addresses take five prefixes: bare <vpath> is this session; @project/<vpath> is this project; @human/<vpath> is the human's cross-project notes; @self/<vpath> is your own, as the current agent; @model/<vpath> is the current model's. @self and @model resolve to who is running now; listings always show resolved names. Nothing else is legal — any other @ prefix, or @ inside a vpath, is a hard error, with no fallback across prefixes.
 Session notes belong to this trip — the goal, the progress, the loose ends. The next window of THIS trip wakes to them; once the trip is over, nobody does.
 @project notes hold facts about this project — architecture, conventions, workflows, deployment and environment details — for whoever works here next.
 @human notes hold the human's durable preferences and standing rules, plus lessons that apply across projects — for every agent that serves this human, whoever is running. You write there as the human's scribe; what the human dictates carries origin: user. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.