@astrosheep/pi-context 0.24.0 → 0.25.0

package/src/context/runtime.ts

@@ -0,0 +1,246 @@
+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 { 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 { registerResetLifecycle } from "./reset-lifecycle.js";
+
+declare const __PI_CONTEXT_BUILD__: { version: string; sourceHash: string };
+
+// The bundle captures its identity; direct source loads must not claim a built hash.
+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));
+}
+
+/** Register the context-window runtime and its context-owned commands/tools. */
+export function registerContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void {
+	let enabled = true;
+	let missingBootNotice: string | undefined;
+	const incompleteNotesNotified = new Set<string>();
+	const pendingResetNotices = new Set<string>();
+	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;
+			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);
+		pendingResetNotices.clear();
+	});
+	const notifyIncompleteNotes: IncompleteNotesNotifier = (ctx, windowId, snapshot) => {
+		if (snapshot.unavailable.length === 0 || incompleteNotesNotified.has(windowId)) return;
+		incompleteNotesNotified.add(windowId);
+		const homes = snapshot.unavailable.map((home) => home.label).join(", ");
+		ctx.ui.notify(`pi-context: notes index incomplete for ${homes}; notes_list can retry after recovery.`, "warning");
+	};
+	const migrationWarning = migrateLegacyHomes();
+	if (migrationWarning) console.warn(`pi-context: ${migrationWarning}`);
+
+	const budget = registerBudget(pi, () => enabled, settingsManager);
+
+	pi.on("session_start", (_event, ctx) => {
+		if (!enabled) return;
+		missingBootNotice = undefined;
+		pendingResetNotices.clear();
+		ensureBoot(pi, ctx, notifyIncompleteNotes);
+	});
+	pi.on("session_tree", (_event, ctx) => {
+		missingBootNotice = undefined;
+		pendingResetNotices.clear();
+		if (enabled) ensureBoot(pi, ctx, notifyIncompleteNotes);
+	});
+
+	// Pi's branch summarizer receives raw entries and bypasses context_with_system. Do not
+	// let a summary of a reset branch smuggle erased history back into the destination.
+	pi.on("session_before_tree", (event, ctx) => {
+		if (!event.preparation.userWantsSummary) return undefined;
+		if (!branchHasWindowMarker(ctx) && !branchHasWindowMarker(ctx, event.preparation.targetId)) return undefined;
+		ctx.ui.notify("pi-context: skipped branch summary across a reset window; navigation continues without erased history.", "info");
+		return { summary: { summary: "" } };
+	});
+
+	// This is the final provider-facing projection. Reset windows cut at their matching boot;
+	// root windows only refresh a forked boot identity and retain the copied root transcript.
+	pi.on("context_with_system", (event, ctx) => {
+		const reset = currentReset(ctx);
+		const windowId = reset?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
+		try {
+			return { messages: reset ? projectWindow(event.messages, windowId) : projectRootWindow(event.messages, windowId) };
+		} catch (error) {
+			if (missingBootNotice !== windowId) {
+				missingBootNotice = windowId;
+				ctx.ui.notify(`pi-context: active context window ${windowId} has no visible boot; request cancelled safely. Use /wipe-memory to start another window.`, "error");
+			}
+			ctx.abort();
+			const safeHead = getCurrentSystemMessage(event.messages);
+			return { messages: safeHead ? [safeHead] : [] };
+		}
+	});
+
+	pi.registerCommand("pi-context", {
+		description: "Show loaded version/build and toggle pi-context context windows",
+		getArgumentCompletions: (prefix) =>
+			["on", "off"].filter((a) => a.startsWith(prefix)).map((a) => ({ value: a, label: a })),
+		handler: async (args, cmdCtx) => {
+			const arg = args.trim().toLowerCase();
+			if (arg === "on") {
+				enabled = true;
+				ensureBoot(pi, cmdCtx, notifyIncompleteNotes);
+			} else if (arg === "off") {
+				enabled = false;
+				budget.clear();
+				resets.clear();
+			} else if (arg !== "") {
+				cmdCtx.ui.notify("Usage: /pi-context [on|off]", "error");
+				return;
+			}
+			cmdCtx.ui.notify(`pi-context: ${enabled ? "on" : "off"} · ${buildLabel} · Pi ${VERSION}`, "info");
+		},
+	});
+
+	pi.registerCommand("wipe-memory", {
+		description: "Persist a fresh context window without calling the model",
+		handler: async (_args, cmdCtx) => {
+			if (!enabled) {
+				cmdCtx.ui.notify("pi-context: /wipe-memory requires /pi-context on.", "error");
+				return;
+			}
+			await cmdCtx.waitForIdle();
+			if (!enabled) return;
+			resets.clear();
+			notifyCommittedResets(cmdCtx, persistManualReset(pi, cmdCtx, notifyIncompleteNotes));
+		},
+	});
+
+	pi.registerTool(defineTool({
+		name: "wipe_memory",
+		label: "Wipe memory",
+		description: "Wipe your in-context memory and start a fresh context window. Your session, notes, and history survive.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute() {
+			if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
+			return output({ status: resets.request() }, undefined, true);
+		},
+	}));
+
+	const resets = registerResetLifecycle(pi, {
+		isEnabled: () => enabled,
+		buildReset: (ctx) => {
+			const drafts = buildResetDrafts(ctx, notifyIncompleteNotes);
+			pendingResetNotices.add(drafts[1].details.windowId);
+			return drafts;
+		},
+		budget,
+	});
+}

package/src/context/thresholds.ts

@@ -0,0 +1,78 @@
+import { SettingsManager, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "../protocol.js";
+import { mergePiContextSettings, type PiContextSettings } from "../settings.js";
+
+export type ResolvedThresholds = { reminder: number; reserve: number; warning: number };
+/** A margin is usable only as a positive integer; anything else is ignored. */
+function validMargin(raw: unknown): number | undefined {
+	if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return undefined;
+	return raw;
+}
+
+/**
+ * Pure derivation of the thresholds from Pi's reserve: the reminder fires at reserve
+ * plus the pi-context margin, the warning steer at reserve plus WARNING_RUNWAY_TOKENS.
+ * An invalid margin degrades to the default and reports one warning. Automatic
+ * threshold/overflow handling is represented by reset lifecycle boundary drafts;
+ * no compaction summary is generated.
+ */
+export function deriveThresholds(reserveTokens: number, margins: PiContextSettings): { thresholds: ResolvedThresholds; warnings: string[] } {
+	const warnings: string[] = [];
+	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+	let reminderMargin: number;
+	if (margins.reminderMarginTokens === undefined) reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+	else {
+		const parsed = validMargin(margins.reminderMarginTokens);
+		if (parsed === undefined) {
+			warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+			reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+		} else reminderMargin = parsed;
+	}
+	return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
+}
+
+/**
+ * Read the active compaction reserve, enablement, and pi-context margin settings. This
+ * function deliberately has no cache: the budget owner supplies the invocation-scoped
+ * cache so two live piContext instances cannot share mutable policy state.
+ */
+export type ThresholdSettingsResolution = {
+	thresholds: ResolvedThresholds;
+	automatic: boolean;
+	warnings: string[];
+};
+
+function readThresholdSettingsFromManager(ctx: ExtensionContext, settingsManager: SettingsManager): ThresholdSettingsResolution {
+	// Resolve the active provider/model override from the public settings API.
+	const model = ctx.model;
+	const compaction = settingsManager.getCompactionSettings(model ? { provider: model.provider, id: model.id } : undefined);
+	const derived = deriveThresholds(
+		compaction.reserveTokens,
+		mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()),
+	);
+	return { thresholds: derived.thresholds, automatic: compaction.enabled, warnings: derived.warnings };
+}
+
+/**
+ * Resolve policy from either the explicitly supplied SDK authority or Pi's default
+ * file-backed settings. The caller owns diagnostics and any lifecycle caching.
+ */
+export function readThresholdSettings(ctx: ExtensionContext, settingsManager?: SettingsManager): ThresholdSettingsResolution {
+	try {
+		if (settingsManager) return readThresholdSettingsFromManager(ctx, settingsManager);
+		return readThresholdSettingsFromManager(
+			ctx,
+			SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() }),
+		);
+	} catch (error) {
+		return {
+			thresholds: {
+				reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS,
+				reserve: DEFAULT_RESERVE_TOKENS,
+				warning: DEFAULT_RESERVE_TOKENS + WARNING_RUNWAY_TOKENS,
+			},
+			automatic: true,
+			warnings: [`pi-context: could not read settings; using defaults (${String(error)}).`],
+		};
+	}
+}

package/src/dream/cli.ts

@@ -6,7 +6,7 @@ import { acquireLock, failLock, lastRunPath, releaseLock } from "./lock.js";
 import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer, type DreamerSessionFactory, type DreamResult, type DreamWrite } from "./runner.js";
 import { gitCommit } from "./git.js";
-import { readDreamerSettings, type DreamerSetting } from "../thresholds.js";
+import { readDreamerSettings, type DreamerSetting } from "./settings.js";
 import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 

package/src/dream/doctor.ts

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, relative } from "node:path";
-import { assertAddress } from "../notes/address.js";
+import { ADDRESS_FORMS, assertAddress } from "../notes/address.js";
+import { SLUG_PATTERN } from "../notes/paths.js";
 
 /** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
 export function doctor(home: string): string[] {
@@ -41,10 +42,17 @@ export function doctor(home: string): string[] {
 			if (!address.startsWith("@") && basename(path) !== "MAP.md") continue;
 			try {
 				const parsed = assertAddress(address);
-				const targetHome = parsed.scope === "personal" ? join(home, "personal") : parsed.scope === "project" ? project : root;
+				// Relative homes (@self/, @model/) name whoever is running; a static doctor
+				// cannot resolve them, so only absolute links are checked.
+				if ((parsed.scope === "agent" || parsed.scope === "model") && parsed.who === undefined) continue;
+				const targetHome = parsed.scope === "human" ? join(home, "human")
+					: parsed.scope === "project" ? project
+					: parsed.scope === "agent" ? join(home, "agents", parsed.who!)
+					: parsed.scope === "model" ? join(home, "models", parsed.who!)
+					: root;
 				if (!targetHome) { report(path, `${address}: project context unavailable; use a resolvable reference`); continue; }
 				if (!existsSync(join(targetHome, parsed.path))) report(path, `${address}: target missing; update or remove the reference`);
-			} catch { report(path, `${address}: invalid address; use bare, @project/ or @personal/ addresses`); }
+			} catch { report(path, `${address}: invalid address; ${ADDRESS_FORMS}`); }
 		}
 	};
 	const walk = (dir: string, root: string, project?: string) => {
@@ -64,14 +72,27 @@ export function doctor(home: string): string[] {
 		for (const name of readdirSync(home)) {
 			const path = join(home, name);
 			inspect(path, () => {
-				if (name === "global") { report(path, "legacy home; manually migrate to personal/ without overwriting existing files"); return; }
+				if (name === "global") { report(path, "legacy home; manually migrate to human/ without overwriting existing files"); return; }
+				if (name === "personal") { report(path, "legacy home; migrate to human/ (rename the directory), merging by hand if human/ already exists"); return; }
 				if (name === ".dream.lock") {
 					const valid = lstatSync(path).isFile() && /^[1-9]\d* [\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\s*$/i.test(readFileSync(path, "utf8"));
 					report(path, `${valid ? "lock present" : "malformed lock"}; verify no dream is running before manual removal; liveness not inferred`);
 					return;
 				}
 				if ([".git", "dreams", "snapshots", "trash", ".dream.lock.last-run"].includes(name)) return;
-				if (name === "personal") { if (directory(path)) walk(path, path); return; }
+				if (name === "human") { if (directory(path)) walk(path, path); return; }
+				if (name === "agents" || name === "models") {
+					if (!directory(path)) return;
+					for (const slug of readdirSync(path)) {
+						const dir = join(path, slug);
+						inspect(dir, () => {
+							if (!SLUG_PATTERN.test(slug)) report(dir, `invalid ${name.slice(0, -1)} slug; expected [a-z0-9-]`);
+							if (!directory(dir)) return;
+							walk(dir, dir);
+						});
+					}
+					return;
+				}
 				if (name === "project" || name === "pi") {
 					if (!directory(path)) return;
 					const homes = name === "pi" ? join(path, "session") : path;
@@ -89,7 +110,7 @@ export function doctor(home: string): string[] {
 					}
 					return;
 				}
-				report(path, "unexpected root entry; expected personal/, project/, pi/session/ or dream artifacts");
+				report(path, "unexpected root entry; expected human/, project/, agents/, models/, pi/session/ or dream artifacts");
 			});
 		}
 	});

package/src/dream/runner.ts

@@ -3,7 +3,7 @@ import { lstat, mkdir, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { createAgentSession, createEditToolDefinition, createWriteToolDefinition, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager, type AgentSession, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { contentText } from "../history.js";
+import { contentText } from "../history/history.js";
 
 export type DreamWrite = { tool: "write" | "edit"; path: string };
 export type DreamResult = { report: string; writes: DreamWrite[]; error?: string };

package/src/dream/settings.ts

@@ -0,0 +1,32 @@
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { PI_CONTEXT_DREAMER_KEY, PI_CONTEXT_SETTINGS_KEY } from "../protocol.js";
+import { mergePiContextSettings, type PiContextSettings } from "../settings.js";
+
+export type DreamerSetting = { pattern?: string; warnings: string[] };
+
+/**
+ * `pi-context.dreamer` is a non-empty model pattern. Anything else present is ignored
+ * with one warning; absent means no configured pattern, so the automatic model applies.
+ */
+export function deriveDreamer(settings: PiContextSettings): DreamerSetting {
+	const raw = settings.dreamer;
+	if (raw === undefined) return { warnings: [] };
+	if (typeof raw !== "string" || raw.trim().length === 0) {
+		return { warnings: [`pi-context: ${PI_CONTEXT_SETTINGS_KEY}.${PI_CONTEXT_DREAMER_KEY} must be a non-empty string; ignoring it.`] };
+	}
+	return { pattern: raw.trim(), warnings: [] };
+}
+
+/**
+ * Resolve the configurable dreamer model from Pi settings for a CLI invocation: global
+ * `~/.pi/agent/settings.json` merged with the project's `.pi/settings.json`, project
+ * values winning per key. A settings read failure degrades to no pattern with one warning.
+ */
+export function readDreamerSettings(cwd = process.cwd()): DreamerSetting {
+	try {
+		const settingsManager = SettingsManager.create(cwd, undefined, { projectTrusted: true });
+		return deriveDreamer(mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
+	} catch (error) {
+		return { warnings: [`pi-context: could not read settings; using the automatic dreamer model (${String(error)}).`] };
+	}
+}

package/src/{history-tools.ts → history/history-tools.ts}

@@ -1,7 +1,7 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, readWindowBlock, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
-import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, readWindowBlock, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "../tool-output.js";
+import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "../tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 
 /**
@@ -46,7 +46,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_list",
 		label: "History list items",
-		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
+		description: "List durable session items, including items from earlier reset windows, using opaque item and window IDs; native compaction and branch summaries remain history items in their current window. The role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
 		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), recent_first: recentFirst(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const invalid = vacuousRoleToolCombo(params);

package/src/{history.ts → history/history.ts}

@@ -1,8 +1,8 @@
 import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { SessionReader } from "./session-reader.js";
-import { RESET_V2 } from "./protocol.js";
-import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
+import type { SessionReader } from "../session-reader.js";
+import { isWindowMarker, rootWindowId } from "../context/context-window.js";
+import { HISTORY_PREVIEW_CHARS } from "../tool-output.js";
 
 type HistoryItem = {
 	windowId: string;
@@ -94,38 +94,22 @@ function toolCallItems(windowId: string, entry: { id: string; timestamp?: string
 	return items;
 }
 
-/** The extension-owned window id baked onto a reset-v2 compaction entry, if present. */
-export function resetV2WindowId(details: unknown): string | undefined {
-	if (typeof details !== "object" || details === null) return undefined;
-	const candidate = details as { piContext?: unknown; windowId?: unknown };
-	if (candidate.piContext !== RESET_V2 || typeof candidate.windowId !== "string") return undefined;
-	return candidate.windowId;
-}
-
-/** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
-export function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
-	return resetV2WindowId(entry.details) ?? `pcw:${sessionId.slice(0, 8)}:${entry.id}`;
-}
-
-/** Mint the durable identity of a session's root history window. */
-export function rootWindowId(sessionId: string): string {
-	return `pcw:${sessionId.slice(0, 8)}:root`;
-}
-
 /** Build durable, on-demand history directly from every entry on the current session branch. */
 export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	const sessionId = ctx.sessionManager.getSessionId();
 	let window: HistoryWindow = { windowId: rootWindowId(sessionId), items: [] };
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
-		if (entry.type === "compaction") {
-			window = { windowId: windowIdOf(sessionId, entry), createdAt: entry.timestamp, items: [] };
+		if (isWindowMarker(entry)) {
+			window = { windowId: entry.data.windowId, createdAt: entry.timestamp, items: [] };
 			windows.push(window);
+			continue;
+		}
+		if (entry.type === "compaction" || entry.type === "branch_summary") {
 			window.items.push({
 				windowId: window.windowId,
 				itemId: entry.id,
-				// A reset-v2 compaction is authored by this extension; a native Pi compaction is not.
-				role: resetV2WindowId(entry.details) === undefined ? "system" : "developer",
+				role: "system",
 				content: entry.summary,
 				createdAt: entry.timestamp,
 			});
@@ -215,26 +199,3 @@ export function filteredItems(ctx: SessionReader, params: HistoryFilter): Histor
 	if (params.recent_first !== false) items.reverse();
 	return items;
 }
-
-
-/** Persisted messages in the active window, excluding earlier windows on this branch. */
-export function hasWindowMessage(ctx: SessionReader, customType: string): boolean {
-	const branch = ctx.sessionManager.getBranch();
-	for (let i = branch.length - 1; i >= 0; i--) {
-		const entry = branch[i];
-		if (entry.type === "compaction") break;
-		if (entry.type === "custom_message" && entry.customType === customType) return true;
-	}
-	return false;
-}
-
-/** Cheap current-window lookup: scan the branch tail for the latest compaction entry. */
-export function currentWindowId(ctx: SessionReader): string {
-	const sessionId = ctx.sessionManager.getSessionId();
-	const branch = ctx.sessionManager.getBranch();
-	for (let i = branch.length - 1; i >= 0; i--) {
-		const entry = branch[i];
-		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
-	}
-	return rootWindowId(sessionId);
-}