@astrosheep/pi-context 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 astrosheep-zero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# pi-context
+
+Codex-style context windows for [Pi](https://github.com/earendil-works/pi-mono): reset-style compaction, durable session-history tools, and persistent notes — implemented entirely with public extension APIs. No Pi core modification required.
+
+## Install
+
+```sh
+pi install npm:@astrosheep/pi-context
+```
+
+Or load it for a single invocation without installing:
+
+```sh
+pi -e npm:@astrosheep/pi-context
+```
+
+## How it works
+
+The extension composes Pi's public `session_before_compact` / `session_compact` hooks, custom session entries, and the `context` hook to approximate Codex's experimental context management:
+
+- **`new_context` tool** — the model requests a fresh context window. The extension waits for the current tool turn to end, compacts with a short deterministic reset message (old conversation is excluded from the new provider context but stays in the session), then sends exactly one hidden continuation turn.
+- **`<context_window>` hint** — every model request carries a Codex-equivalent fragment with the agent name, first/current/previous window IDs, and the 5 most recently updated notes. The model gets recovery entry points, not a bare "go search" message.
+- **History tools** — the model searches pre-reset conversation with case-sensitive literal substring search, exactly like Codex's `history.*` namespace.
+- **Notes tools** — persistent, session-scoped virtual files that survive window resets.
+
+## Tools
+
+The nine Codex History/Notes actions are flattened because Pi tools have one global name space:
+
+| Codex action | Pi tool |
+| --- | --- |
+| `history.list_windows` | `history_list_windows` |
+| `history.list_items` | `history_list_items` |
+| `history.read_item` | `history_read_item` |
+| `history.search_contents` | `history_search_contents` |
+| `notes.list_files_by_prefix` | `notes_list_files_by_prefix` |
+| `notes.read_file` | `notes_read_file` |
+| `notes.search_contents` | `notes_search_contents` |
+| `notes.append_to_file` | `notes_append_to_file` |
+| `notes.write_file` | `notes_write_file` |
+
+`history_*` reads the current branch's actual Pi session entries, including entries hidden by earlier compaction. Window IDs are stable `pcw:<session-id>:root` or `pcw:<session-id>:<compaction-entry-id>` identifiers; item IDs are the persisted Pi entry IDs. No transcript copy or volatile archive is maintained.
+
+`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. Writes are capped at 1,000,000 UTF-8 bytes.
+
+Pi has no public cross-agent session router. Passing `agent_name` to a history tool returns an explicit unsupported error; it is never silently redirected to the current session.
+
+Two extra controls compose Pi public APIs:
+
+- `get_context_remaining` returns `{ "remaining_tokens": number | null }`. `null` means Pi itself cannot make a reliable estimate (notably immediately after compaction).
+- `new_context` returns terminal tool output, then waits for Pi's `agent_end`, triggers public `ctx.compact()`, installs a short deterministic reset compaction, and sends exactly one hidden continuation turn after compaction succeeds. Call it by itself in a tool batch. Pi only ends a tool turn when every parallel tool result is terminal, so Pi 0.85.1 cannot force an atomic rollover from the middle of a mixed parallel tool batch.
+
+## Reset behavior and limits
+
+On `session_before_compact`, the extension appends a persistent custom reset marker through public `pi.appendEntry`, reads that real marker ID from the readonly session manager, and returns it as `firstKeptEntryId`. Pi's `buildContextEntries()` then keeps the compaction envelope plus that custom marker; custom markers are excluded from LLM context. Thus the subsequent provider context contains the short reset result and hidden continuation, not old conversation messages. The old entries remain only in the session tree for `history_*`.
+
+The same handler is used for native automatic compaction. When Pi marks an overflow compaction `willRetry`, Pi core performs its single retry itself and this extension deliberately sends no second continuation.
+
+This is a composition of public `session_before_compact`, `session_compact`, `pi.appendEntry`, `ctx.compact`, and `pi.sendMessage`; it is not a Pi-core `newSession` call. A manual Pi compaction is only eligible when Pi's own `prepareCompaction()` accepts the session. Therefore a `new_context` request in a too-small/uncompactable session fails cleanly without default-summary fallback or continuation. A core change would be needed only to guarantee a force-reset at arbitrary small context sizes or to atomically interrupt a mixed parallel tool batch.
+
+## Verification
+
+```sh
+npm run typecheck
+npm test
+```
+
+The integration harness uses the installed Pi `SessionManager`, including an on-disk JSONL reload. It verifies note persistence/Unicode/path rules, provider context exclusion after the real `firstKeptEntryId` boundary while history remains searchable, completed tool-result boundary placement, one continuation only, and cancellation/failure/no-double-retry behavior. It uses no model or network call.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@astrosheep/pi-context",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
+  "license": "MIT",
+  "keywords": ["pi-package", "pi-extension", "context-management"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astrosheep-zero/pi-context.git"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/test/integration.test.js",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,417 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const STATE_TYPE = "pi-context/state";
+const NOTE_TYPE = "pi-context/note";
+const RESET_MARKER_TYPE = "pi-context/reset-marker";
+const CONTINUATION_TYPE = "pi-context/continuation";
+const MAX_NOTE_BYTES = 1_000_000;
+const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
+const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
+const RESET_SUMMARY = "Context window reset. Prior session entries remain available only through the pi-context history tools.";
+const CONTINUATION = "This is a fresh context window. Recover only the details needed to continue with history_* and notes_*; then continue the task.";
+
+type Json = Record<string, unknown>;
+type NoteFile = { text: string; createdAt: number; updatedAt: number };
+type NoteOperation = {
+	op: "write" | "append";
+	path: string;
+	text: string;
+	createdAt: number;
+	updatedAt: number;
+};
+type HistoryItem = {
+	windowId: string;
+	itemId: string;
+	role: "user" | "assistant" | "tool" | "system" | "developer";
+	content: string;
+	createdAt: string | undefined;
+	toolName?: string;
+	toolNamespace?: string;
+};
+type HistoryWindow = { windowId: string; createdAt?: string; items: HistoryItem[] };
+
+function json(value: unknown): string {
+	return JSON.stringify(value, null, 2);
+}
+
+function output(value: unknown, details: unknown = value, terminate = false) {
+	return { content: [{ type: "text" as const, text: json(value) }], details, terminate };
+}
+
+function unsupportedAgent(agentName: unknown) {
+	return agentName !== undefined && agentName !== null
+		? { error: "Pi 0.85.1 exposes no cross-agent session routing; agent_name is unsupported and was not aliased to this session." }
+		: undefined;
+}
+
+function toText(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		return value
+			.map((part) => {
+				if (typeof part === "string") return part;
+				if (part && typeof part === "object" && typeof (part as Json).text === "string") return (part as Json).text as string;
+				return JSON.stringify(part);
+			})
+			.join("\n");
+	}
+	return value === undefined || value === null ? "" : JSON.stringify(value);
+}
+
+function mapRole(role: unknown): HistoryItem["role"] | undefined {
+	if (role === "user" || role === "assistant" || role === "system" || role === "developer") return role;
+	if (role === "toolResult" || role === "tool") return "tool";
+	return undefined;
+}
+
+function toolInfo(message: Json): Pick<HistoryItem, "toolName" | "toolNamespace"> {
+	const name = typeof message.toolName === "string" ? message.toolName : undefined;
+	if (!name) return {};
+	const underscore = name.indexOf("_");
+	return { toolName: name, toolNamespace: underscore > 0 ? name.slice(0, underscore) : undefined };
+}
+
+/** Build durable, on-demand history directly from every entry on the current session branch. */
+export function historyFromSession(ctx: ExtensionContext): HistoryWindow[] {
+	const sessionId = ctx.sessionManager.getSessionId();
+	let window: HistoryWindow = { windowId: `pcw:${sessionId}:root`, items: [] };
+	const windows = [window];
+	for (const entry of ctx.sessionManager.getBranch() as unknown as Array<Json>) {
+		if (entry.type === "compaction") {
+			window = { windowId: `pcw:${sessionId}:${String(entry.id)}`, createdAt: typeof entry.timestamp === "string" ? entry.timestamp : undefined, items: [] };
+			windows.push(window);
+			window.items.push({
+				windowId: window.windowId,
+				itemId: String(entry.id),
+				role: "system",
+				content: typeof entry.summary === "string" ? entry.summary : "",
+				createdAt: typeof entry.timestamp === "string" ? entry.timestamp : undefined,
+			});
+			continue;
+		}
+		if (entry.type === "message") {
+			const message = entry.message as Json;
+			const role = mapRole(message.role);
+			if (!role) continue;
+			window.items.push({
+				windowId: window.windowId,
+				itemId: String(entry.id),
+				role,
+				content: toText(message.content),
+				createdAt: typeof entry.timestamp === "string" ? entry.timestamp : undefined,
+				...toolInfo(message),
+			});
+			continue;
+		}
+		if (entry.type === "custom_message") {
+			window.items.push({
+				windowId: window.windowId,
+				itemId: String(entry.id),
+				role: "user",
+				content: toText(entry.content),
+				createdAt: typeof entry.timestamp === "string" ? entry.timestamp : undefined,
+			});
+		}
+	}
+	return windows;
+}
+
+function visibleItem(item: HistoryItem, maxChars = 1200) {
+	const characters = Array.from(item.content);
+	return {
+		window_id: item.windowId,
+		item_id: item.itemId,
+		role: item.role,
+		tool_namespace: item.toolNamespace ?? null,
+		tool_name: item.toolName ?? null,
+		truncated_content: characters.length > maxChars ? `${characters.slice(0, maxChars).join("")}…` : item.content,
+	};
+}
+
+function allItems(ctx: ExtensionContext) {
+	return historyFromSession(ctx).flatMap((window) => window.items);
+}
+
+function filteredItems(ctx: ExtensionContext, params: Json): HistoryItem[] | { error: string } {
+	const agentError = unsupportedAgent(params.agent_name);
+	if (agentError) return agentError;
+	let items = allItems(ctx);
+	if (typeof params.window_id === "string") items = items.filter((item) => item.windowId === params.window_id);
+	if (typeof params.role === "string") items = items.filter((item) => item.role === params.role);
+	if (typeof params.tool_namespace === "string") items = items.filter((item) => item.toolNamespace === params.tool_namespace);
+	if (typeof params.tool_name === "string") items = items.filter((item) => item.toolName === params.tool_name);
+	if (params.recent_first === true) items.reverse();
+	return items;
+}
+
+function assertVirtualPath(value: unknown): string {
+	if (typeof value !== "string" || value.length === 0) throw new Error("path must be a non-empty virtual relative path");
+	if (value.includes("\0") || value.includes("\\") || value.startsWith("/")) throw new Error("path must be a safe virtual relative path");
+	const parts = value.split("/");
+	if (parts.some((part) => part.length === 0 || part === "." || part === "..")) throw new Error("path contains an unsupported component");
+	return value;
+}
+
+function assertVirtualPrefix(value: unknown): string | undefined {
+	if (value === undefined || value === null || value === "") return undefined;
+	return assertVirtualPath(value);
+}
+
+export function notesFromSession(ctx: ExtensionContext): Map<string, NoteFile> {
+	const files = new Map<string, NoteFile>();
+	for (const entry of ctx.sessionManager.getBranch() as unknown as Array<Json>) {
+		if (entry.type !== "custom" || entry.customType !== NOTE_TYPE || !entry.data || typeof entry.data !== "object") continue;
+		const op = entry.data as Partial<NoteOperation>;
+		if ((op.op !== "write" && op.op !== "append") || typeof op.path !== "string" || typeof op.text !== "string") continue;
+		try {
+			assertVirtualPath(op.path);
+		} catch {
+			continue;
+		}
+		const previous = files.get(op.path);
+		const createdAt = typeof op.createdAt === "number" ? op.createdAt : previous?.createdAt ?? 0;
+		const updatedAt = typeof op.updatedAt === "number" ? op.updatedAt : createdAt;
+		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, updatedAt });
+	}
+	return files;
+}
+
+/** Codex-equivalent <context_window> hint: window identity plus recent-notes entry points. */
+export function contextWindowHint(ctx: ExtensionContext): string {
+	const windows = historyFromSession(ctx);
+	const first = windows[0];
+	const current = windows[windows.length - 1];
+	const previous = windows.length > 1 ? windows[windows.length - 2] : undefined;
+	const lines = [
+		`Agent name: ${ctx.sessionManager.getSessionName() ?? "root"}`,
+		`First context window id: ${first?.windowId ?? "unknown"}`,
+		`Current context window id: ${current?.windowId ?? "unknown"}`,
+	];
+	if (previous) lines.push(`Previous context window id: ${previous.windowId}`);
+	const recentNotes = [...notesFromSession(ctx)]
+		.sort((a, b) => b[1].updatedAt - a[1].updatedAt)
+		.slice(0, 5);
+	if (recentNotes.length > 0) {
+		lines.push("Recent notes (up to 5, most-recent first):");
+		for (const [path, file] of recentNotes) {
+			lines.push(`- ${path} (${file.text.split("\n").length} lines, ${Buffer.byteLength(file.text, "utf8")} UTF-8 bytes)`);
+		}
+	}
+	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
+}
+
+function lineRange(text: string, startValue: unknown, stopValue: unknown) {
+	const lines = text.split("\n");
+	const resolve = (value: unknown, fallback: number) => {
+		if (value === undefined || value === null) return fallback;
+		if (!Number.isInteger(value) || value === 0) throw new Error("line numbers must be non-zero integers; negative values count from the end");
+		const line = value as number;
+		return line > 0 ? line : lines.length + line + 1;
+	};
+	const start = Math.max(1, resolve(startValue, 1));
+	const stop = Math.min(lines.length, resolve(stopValue, lines.length));
+	return { start_line: start, stop_line: stop, content: start > stop ? "" : lines.slice(start - 1, stop).join("\n") };
+}
+
+const nullableString = () => Type.Optional(Type.Union([Type.String(), Type.Null()]));
+const nullableInteger = () => Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
+const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }));
+const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()]);
+
+export default function piContext(pi: ExtensionAPI) {
+	let rollover: "idle" | "requested" | "compacting" | "continued" = "idle";
+	const saveNote = (op: NoteOperation) => {
+		// pi.appendEntry writes a custom SessionManager entry. Custom entries are persistent but excluded from LLM context.
+		// ExtensionContext deliberately exposes only a readonly SessionManager, so this is the public extension write path.
+		pi.appendEntry(NOTE_TYPE, op);
+	};
+
+	pi.registerTool(defineTool({
+		name: "history_list_windows",
+		label: "History list windows",
+		description: "List durable Pi session-history windows. agent_name is explicitly unsupported because Pi has no cross-agent session routing.",
+		parameters: Type.Object({ limit: positiveInteger(), agent_name: nullableString(), recent_first: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const agentError = unsupportedAgent(params.agent_name);
+			if (agentError) return output(agentError);
+			let windows = historyFromSession(ctx);
+			if (params.recent_first) windows = [...windows].reverse();
+			const limit = params.limit ?? windows.length;
+			return output({ windows: windows.slice(0, limit).map((window) => ({ window_id: window.windowId, item_count: window.items.length })) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "history_list_items",
+		label: "History list items",
+		description: "List durable session items, including items before compaction, using opaque item and window IDs.",
+		parameters: Type.Object({ limit: positiveInteger(), recent_first: Type.Optional(Type.Boolean()), tool_namespace: nullableString(), role: Type.Optional(role), agent_name: nullableString(), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const items = filteredItems(ctx, params);
+			if ("error" in items) return output(items);
+			return output({ items: items.slice(0, params.limit ?? items.length).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200)) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "history_read_item",
+		label: "History read item",
+		description: "Read a bounded character range from one durable session item.",
+		parameters: Type.Object({ agent_name: nullableString(), item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ minimum: 0 })), limit_chars: positiveInteger(), window_id: Type.String() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const agentError = unsupportedAgent(params.agent_name);
+			if (agentError) return output(agentError);
+			const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
+			if (!item) return output({ error: "unknown item_id or window_id" });
+			const chars = Array.from(item.content);
+			const offset = params.offset_chars ?? 0;
+			const limit = params.limit_chars ?? chars.length;
+			return output({ window_id: item.windowId, item_id: item.itemId, offset_chars: offset, content: chars.slice(offset, offset + limit).join("") });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "history_search_contents",
+		label: "History search",
+		description: "Case-sensitive literal substring search over durable Pi session history; no semantic search.",
+		parameters: Type.Object({ limit: positiveInteger(), query: Type.String(), recent_first: Type.Optional(Type.Boolean()), tool_namespace: nullableString(), role: Type.Optional(role), agent_name: nullableString(), tool_name: nullableString(), window_id: nullableString() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const items = filteredItems(ctx, params);
+			if ("error" in items) return output(items);
+			const matching = items.filter((item) => item.content.includes(params.query));
+			return output({ items: matching.slice(0, params.limit ?? matching.length).map((item) => visibleItem(item)) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_list_files_by_prefix",
+		label: "Notes list files",
+		description: "List persistent, session-scoped virtual note files.",
+		parameters: Type.Object({ prefix: nullableString(), max_results: positiveInteger(), file_order_by: Type.Optional(Type.Union([Type.Literal("name"), Type.Literal("created_at"), Type.Literal("updated_at")])), file_order: Type.Optional(Type.Union([Type.Literal("ascending"), Type.Literal("descending")])) }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const prefix = assertVirtualPrefix(params.prefix);
+			let files = [...notesFromSession(ctx)].filter(([path]) => !prefix || path.startsWith(prefix));
+			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();
+			return output({ files: files.slice(0, params.max_results ?? files.length).map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), created_at: file.createdAt, updated_at: file.updatedAt })) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_read_file",
+		label: "Notes read file",
+		description: "Read a virtual note file, optionally by inclusive 1-based line range; negative lines count from the end.",
+		parameters: Type.Object({ path: Type.String(), start_line: nullableInteger(), stop_line: nullableInteger() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const path = assertVirtualPath(params.path);
+			const file = notesFromSession(ctx).get(path);
+			if (!file) return output({ error: "note file not found", path });
+			return output({ path, ...lineRange(file.text, params.start_line, params.stop_line) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_search_contents",
+		label: "Notes search",
+		description: "Case-sensitive literal substring search over virtual note lines; no semantic search.",
+		parameters: Type.Object({ max_matches_per_file: positiveInteger(), query: Type.String(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const prefix = assertVirtualPrefix(params.path_prefix);
+			let files = [...notesFromSession(ctx)].filter(([path]) => !prefix || path.startsWith(prefix));
+			if (params.recent_file_first) files.sort((a, b) => b[1].createdAt - a[1].createdAt);
+			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
+			const result = files.map(([path, file]) => ({ path, matches: file.text.split("\n").flatMap((line, index) => line.includes(params.query) ? [{ line: index + 1, text: line }] : []).slice(0, maxPerFile) })).filter((file) => file.matches.length > 0);
+			return output({ files: result.slice(0, params.max_files ?? result.length) });
+		},
+	}));
+
+	for (const [name, op] of [["notes_append_to_file", "append"], ["notes_write_file", "write"]] as const) {
+		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 }),
+			async execute(_id, params, _signal, _update, ctx) {
+				const path = assertVirtualPath(params.path);
+				const old = notesFromSession(ctx).get(path);
+				const next = op === "append" ? `${old?.text ?? ""}${params.text}` : params.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 });
+				const now = Date.now();
+				saveNote({ op, path, text: params.text, createdAt: old?.createdAt ?? now, updatedAt: now });
+				return output({ path, size_bytes: bytes, operation: op });
+			},
+		}));
+	}
+
+	pi.on("context", (event, ctx) => {
+		// Rebuilt per request, so no state diffing is needed; identical to Codex's
+		// context_window developer fragment rendered into each model call.
+		const hint = {
+			role: "user" as const,
+			content: [{ type: "text" as const, text: contextWindowHint(ctx) }],
+			timestamp: Date.now(),
+		};
+		return { messages: [hint, ...event.messages] };
+	});
+
+	pi.registerTool(defineTool({
+		name: "get_context_remaining",
+		label: "Get context remaining",
+		description: "Return remaining context tokens when Pi can estimate them, otherwise null.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute(_id, _params, _signal, _update, ctx) {
+			const usage = ctx.getContextUsage();
+			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens);
+			return output({ remaining_tokens: remaining });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "new_context",
+		label: "New context",
+		description: "Request a reset-style context rollover after this tool result is safely recorded. Call alone in a tool batch.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute() {
+			if (rollover === "idle") rollover = "requested";
+			return output({ status: rollover === "requested" ? "rollover_requested" : "rollover_already_pending" }, undefined, true);
+		},
+	}));
+
+	pi.on("agent_end", (_event, ctx) => {
+		if (rollover !== "requested") return;
+		rollover = "compacting";
+		ctx.compact({ onError: () => { if (rollover === "compacting") rollover = "idle"; } });
+	});
+
+	pi.on("session_before_compact", async (event, ctx) => {
+		// Never let an aborted or failed custom reset fall through to Pi's default summary.
+		if (event.signal.aborted) return { cancel: true };
+		try {
+			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: rollover === "compacting" });
+			const markerId = ctx.sessionManager.getLeafId();
+			if (!markerId) return { cancel: true };
+			return { compaction: { summary: RESET_SUMMARY, firstKeptEntryId: markerId, tokensBefore: event.preparation.tokensBefore, details: { piContext: "reset-v1" } } };
+		} catch {
+			return { cancel: true };
+		}
+	});
+
+	pi.on("session_compact", (event) => {
+		// Overflow retry is already continued once by Pi core. Sending another turn would duplicate it.
+		if (event.willRetry) return;
+		if (rollover !== "compacting") return;
+		rollover = "continued";
+		pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: event.compactionEntry.id });
+		pi.sendMessage({ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }, { triggerTurn: true });
+	});
+
+	pi.on("session_compact_failed", () => {
+		if (rollover === "compacting") rollover = "idle";
+	});
+}
+
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, lineRange, assertVirtualPath };