@astrosheep/pi-context 0.24.0 → 0.25.0

package/src/notes/store.ts

@@ -3,11 +3,10 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, w
 import { dirname } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { generateDiffString } from "@earendil-works/pi-coding-agent";
-import { assertGlobPattern, assertVirtualPath, globToRegExp } from "./model.js";
 import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "../protocol.js";
 import { isOrigin, isScope, parseNote, serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
-import { addressFor } from "./address.js";
-import { physicalPath, scopeDir, type Scope } from "./paths.js";
+import { addressFor, assertGlobPattern, assertVirtualPath, globToRegExp } from "./address.js";
+import { agentSlug, modelSlug, namespaceSlugs, physicalPath, scopeDir, type Scope } from "./paths.js";
 import { earliestMatchOffsetChars } from "../tool-output.js";
 
 export type { NoteMeta, Origin, Scope };
@@ -32,10 +31,10 @@ export type NoteRow = { address: string; scope: Scope; path: string; meta: NoteM
 export type NoteMatch = { line: number; text: string; offsetChars: number };
 export type NoteSearchRow = { address: string; scope: Scope; path: string; meta: NoteMeta; matches: NoteMatch[] };
 
-const SCOPE_ORDER: readonly Scope[] = ["session", "project", "personal"];
+const SCOPE_ORDER: readonly Scope[] = ["session", "project", "human", "agent", "model"];
 
 function assertScope(value: unknown): Scope {
-	if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, personal (got ${JSON.stringify(value)})`);
+	if (!isScope(value)) throw new NoteError("invalid_scope", `scope must be one of session, project, human, agent, model (got ${JSON.stringify(value)})`);
 	return value;
 }
 
@@ -49,8 +48,12 @@ function walkMarkdown(dir: string, base = dir): string[] {
 	let entries: Dirent[];
 	try {
 		entries = readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return [];
+	} catch (error) {
+		// A home that has never been created is normal. Every other directory
+		// failure must reach the boot snapshot boundary instead of masquerading as
+		// an empty home.
+		if (typeof error === "object" && error !== null && (error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
 	}
 	const paths: string[] = [];
 	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
@@ -99,6 +102,52 @@ function frontmatterOf(meta: NoteMeta): string {
 	return serializeNote(meta, "").slice(0, -2);
 }
 
+/** Named agent/model homes are read-only to whoever is not running there. */
+function assertWritableHome(scope: Scope, who: string | undefined, ctx: ExtensionContext): void {
+	if (who === undefined) return;
+	const current = scope === "agent" ? agentSlug(ctx) : modelSlug(ctx);
+	if (who === current) return;
+	const home = scope === "agent" ? `@agents/${who}/` : `@models/${who}/`;
+	throw new NoteError("invalid_scope", `${home} is not your home: writable homes are this session, @project/, @human/, @self/, and the current @model/ home`);
+}
+
+/**
+ * Which homes one call iterates. A pattern whose head is a reserved home narrows the set
+ * before any file is read; `@agents/<name>/` and `@models/<name>/` address one home, a glob
+ * in the name segment scans the whole namespace, and an unknown `@` head matches nothing.
+ * Undefined means the default merged view: session, project, human, your own agent home,
+ * and the current model home.
+ */
+type HomeRef = { scope: Scope; who?: string };
+
+function homesForPattern(pattern: string | undefined): HomeRef[] | undefined {
+	if (!pattern || !pattern.startsWith("@")) return undefined;
+	const head = /^@([^/]+)\//.exec(pattern)?.[1];
+	if (head === "project") return [{ scope: "project" }];
+	if (head === "human") return [{ scope: "human" }];
+	if (head === "self") return [{ scope: "agent" }];
+	if (head === "model") return [{ scope: "model" }];
+	if (head === "agents" || head === "models") {
+		const scope: Scope = head === "agents" ? "agent" : "model";
+		const name = pattern.slice(head.length + 2).split("/")[0] ?? "";
+		if (name.length > 0 && !/[*?]/.test(name)) return [{ scope, who: name }];
+		return namespaceSlugs(head).map((who) => ({ scope, who }));
+	}
+	return [];
+}
+
+/** Relative pattern heads resolve to canonical names, so they match rendered addresses. */
+function normalizePattern(pattern: string | undefined, ctx: ExtensionContext): string | undefined {
+	if (!pattern) return pattern;
+	if (pattern.startsWith("@self/")) return `@agents/${agentSlug(ctx)}/${pattern.slice("@self/".length)}`;
+	if (pattern.startsWith("@model/")) return `@models/${modelSlug(ctx)}/${pattern.slice("@model/".length)}`;
+	return pattern;
+}
+
+function homesFor(ctx: ExtensionContext, opts: { scope?: Scope; who?: string; pattern?: string }): HomeRef[] {
+	if (opts.scope !== undefined) return [{ scope: opts.scope, who: opts.who }];
+	return homesForPattern(opts.pattern) ?? SCOPE_ORDER.map((scope) => ({ scope }));
+}
 /** Line numbers (1-based) of every occurrence of `needle` in `body`. */
 function matchLineNumbers(body: string, needle: string): number[] {
 	const lines: number[] = [];
@@ -112,15 +161,16 @@ function matchLineNumbers(body: string, needle: string): number[] {
 	return lines;
 }
 
-export type WriteOptions = { scope: Scope; origin: Origin; stale?: boolean };
+export type WriteOptions = { scope: Scope; who?: string; origin: Origin; stale?: boolean };
 
 /** Create or overwrite a note; overwrite keeps created_at and every unknown key. */
 export function writeNote(ctx: ExtensionContext, vpath: string, body: string, opts: WriteOptions): { meta: NoteMeta } {
 	assertVirtualPath(vpath);
 	assertWritablePath(vpath);
 	const scope = assertScope(opts.scope);
+	assertWritableHome(scope, opts.who, ctx);
 	const origin = assertOrigin(opts.origin);
-	const path = physicalPath(scope, vpath, ctx);
+	const path = physicalPath(scope, vpath, ctx, opts.who);
 	const now = Date.now();
 	const cleanBody = stripLeadingFrontmatter(body);
 	const existing = existsSync(path) ? parseNote(readFileSync(path, "utf8"), now).meta : undefined;
@@ -149,9 +199,9 @@ export type EditOperation = { oldText: string; newText: string };
 export type EditOptions = { origin?: Origin; stale?: boolean; replaceAll?: boolean };
 
 /** Dream harness mutation: metadata changes still use the store's atomic writer. */
-export function updateNoteMeta(ctx: ExtensionContext, vpath: string, scope: Scope, mutate: (meta: NoteMeta) => void): { meta: NoteMeta; body: string } {
+export function updateNoteMeta(ctx: ExtensionContext, vpath: string, scope: Scope, mutate: (meta: NoteMeta) => void, who?: string): { meta: NoteMeta; body: string } {
 	assertVirtualPath(vpath);
-	const path = physicalPath(scope, vpath, ctx);
+	const path = physicalPath(scope, vpath, ctx, who);
 	if (!existsSync(path)) throw new NoteError("not_found", `note not found: ${vpath}`);
 	const parsed = parseNote(readFileSync(path, "utf8"));
 	const meta = { ...parsed.meta, scope };
@@ -164,14 +214,15 @@ export function updateNoteMeta(ctx: ExtensionContext, vpath: string, scope: Scop
 }
 
 /** Apply body-only edits against one explicit home; origin and stale are its metadata setters. */
-export function editNote(ctx: ExtensionContext, vpath: string, scope: Scope, edits: EditOperation[] | undefined, opts: EditOptions = {}): { meta: NoteMeta; applied: number; resolved_scope: Scope; diff: string } {
+export function editNote(ctx: ExtensionContext, vpath: string, scope: Scope, edits: EditOperation[] | undefined, opts: EditOptions = {}, who?: string): { meta: NoteMeta; applied: number; resolved_scope: Scope; diff: string } {
 	assertVirtualPath(vpath);
 	assertWritablePath(vpath);
+	assertWritableHome(scope, who, ctx);
 	const operations = edits ?? [];
 	if (operations.length === 0 && opts.origin === undefined && opts.stale === undefined) {
 		throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
 	}
-	const path = physicalPath(scope, vpath, ctx);
+	const path = physicalPath(scope, vpath, ctx, who);
 	if (!existsSync(path)) throw new NoteError("not_found", "note not found");
 	const raw = readFileSync(path, "utf8");
 	const { meta, body } = parseNote(raw);
@@ -229,9 +280,9 @@ function accessedMeta(meta: NoteMeta, scope: Scope, now: number): NoteMeta {
 }
 
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; text: string; resolvedScope: Scope } | undefined {
+export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope, who?: string): { meta: NoteMeta; body: string; text: string; resolvedScope: Scope } | undefined {
 	assertVirtualPath(vpath);
-	const path = physicalPath(scope, vpath, ctx);
+	const path = physicalPath(scope, vpath, ctx, who);
 	if (!existsSync(path)) return undefined;
 	const now = Date.now();
 	const parsed = parseNote(readFileSync(path, "utf8"), now);
@@ -242,13 +293,14 @@ export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): {
 }
 
 /** Merged rows across homes, most recently updated first (address breaks ties). */
-export function listNotes(ctx: ExtensionContext, opts: { scope?: Scope; pattern?: string } = {}): NoteRow[] {
-	const matcher = matcherFor(opts.pattern);
+export function listNotes(ctx: ExtensionContext, opts: { scope?: Scope; who?: string; pattern?: string } = {}): NoteRow[] {
+	const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
 	const rows: NoteRow[] = [];
-	for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
-		const root = scopeDir(scope, ctx);
+	for (const home of homesFor(ctx, opts)) {
+		const scope = home.scope;
+		const root = scopeDir(scope, ctx, home.who);
 		for (const path of walkMarkdown(root)) {
-			const address = addressFor(scope, path);
+			const address = addressFor(ctx, scope, path, home.who);
 			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;
@@ -260,13 +312,14 @@ export function listNotes(ctx: ExtensionContext, opts: { scope?: Scope; pattern?
 }
 
 /** Case-sensitive literal substring search over note bodies, with a match address per line. */
-export function searchNotes(ctx: ExtensionContext, queries: string[], opts: { scope?: Scope; pattern?: string } = {}): NoteSearchRow[] {
-	const matcher = matcherFor(opts.pattern);
+export function searchNotes(ctx: ExtensionContext, queries: string[], opts: { scope?: Scope; who?: string; pattern?: string } = {}): NoteSearchRow[] {
+	const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
 	const rows: NoteSearchRow[] = [];
-	for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
-		const root = scopeDir(scope, ctx);
+	for (const home of homesFor(ctx, opts)) {
+		const scope = home.scope;
+		const root = scopeDir(scope, ctx, home.who);
 		for (const path of walkMarkdown(root)) {
-			const address = addressFor(scope, path);
+			const address = addressFor(ctx, scope, path, home.who);
 			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;

package/src/notes/tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { localIso } from "./model.js";
+import { localIso } from "./frontmatter.js";
 import { DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, readWindowBlock, withinTextBudget } from "../tool-output.js";
 import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
 import { assertAddress } from "./address.js";
@@ -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's home, and `@personal/<vpath>` for the human's cross-project home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@personal/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
+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.";
 
 function failure(error: unknown) {
 	if (error instanceof NoteError) {
@@ -31,7 +31,7 @@ export function registerNotesTools(pi: ExtensionAPI) {
 			const content = params.content;
 			try {
 				const destination = assertAddress(params.address);
-				writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				writeNote(ctx, destination.path, content, { scope: destination.scope, who: destination.who, origin: (params.origin ?? "self") as Origin, stale: params.stale });
 				return output({ address: params.address, written: true });
 			} catch (error) { return failure(error); }
 		},
@@ -44,7 +44,7 @@ export function registerNotesTools(pi: ExtensionAPI) {
 		async execute(_id, params, _signal, _update, ctx) {
 			try {
 				const destination = assertAddress(params.address);
-				const { applied, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				const { applied, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all }, destination.who);
 				return output({ address: params.address, applied, diff });
 			} catch (error) { return failure(error); }
 		},
@@ -58,7 +58,7 @@ export function registerNotesTools(pi: ExtensionAPI) {
 			let note: ReturnType<typeof readNote>;
 			try {
 				const destination = assertAddress(params.address);
-				note = readNote(ctx, destination.path, destination.scope);
+				note = readNote(ctx, destination.path, destination.scope, destination.who);
 			} catch (error) { return failure(error); }
 			if (!note) return output({ error: "note not found", address: params.address });
 			const text = note.text;
@@ -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} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
+		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).`,
 		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} All three homes are merged and every entry carries its full address. 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 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.`,
 		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

@@ -1,15 +1,15 @@
-export const STATE_TYPE = "pi-context/state";
 export const NOTE_TYPE = "pi-context/note";
 export const BOOT_TYPE = "pi-context/boot";
 export const GUIDANCE_TYPE = "pi-context/guidance";
 export const WARNING_TYPE = "pi-context/warning";
 export const RESET_MARKER_TYPE = "pi-context/reset-marker";
 export const CONTINUATION_TYPE = "pi-context/continuation";
-export const RESET_V2 = "reset-v2";
 export const MAX_NOTE_BYTES = 1_000_000;
 export const POCKET_SESSION_LIMIT = 5;
 export const POCKET_PROJECT_LIMIT = 2;
-export const POCKET_PERSONAL_LIMIT = 2;
+export const POCKET_HUMAN_LIMIT = 2;
+export const POCKET_AGENT_LIMIT = 1;
+export const POCKET_MODEL_LIMIT = 1;
 // Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
 // notesFromSession replays already-persisted operations, which must keep loading sessions
 // that contain a longer legacy path. Reads and replay stay un-capped.
@@ -51,10 +51,12 @@ Use get_context_remaining to see how much of the window is left. When it runs ou
 
 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.
 
-Your notes live in three homes: this session (bare names), this project (@project/<vpath>), the human across projects (@personal/<vpath>). @ means leaving home — and homes don't visit each other: there is no cross-home fallback.
+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.
 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.
-@personal notes hold the human's durable preferences and standing rules, plus lessons that apply across projects. Duration does not make a note personal; its stated scope must already be broader than the project or conversation at hand. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.
+@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.
+@self notes are yours — your voice, your lessons, your gripes — for the next run of whoever you are. Other agents read yours by explicit address and never write them; you read theirs the same way. A note only its author would ever need belongs here, not in @human.
+@model notes capture the substrate — how the current model actually behaves: context honesty, tool quirks, fallback patterns. @model resolves live, so what you learn on one model is filed under that model even when a fallback moves you mid-window.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 
 export const WARNING_PROMPT =

package/src/settings.ts

@@ -0,0 +1,20 @@
+import { PI_CONTEXT_SETTINGS_KEY } from "./protocol.js";
+
+export type PiContextSettings = { reminderMarginTokens?: unknown; dreamer?: unknown };
+
+function isSettingsObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read the raw "pi-context" object from one parsed settings scope. */
+function piContextSettings(settings: unknown): Record<string, unknown> {
+	if (!isSettingsObject(settings)) return {};
+	const value = settings[PI_CONTEXT_SETTINGS_KEY];
+	return isSettingsObject(value) ? value : {};
+}
+
+/** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
+export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextSettings {
+	const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
+	return { reminderMarginTokens: merged.reminderMarginTokens, dreamer: merged.dreamer };
+}

package/src/tool-schema.ts

@@ -4,7 +4,7 @@ export const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }))
 export const cursor = () => Type.Optional(Type.Integer({ minimum: 0, description: "Continuation cursor: pass the previous next_cursor back unchanged, with the same filters and ordering. Omit to start. next_cursor is null only when the set is exhausted." }));
 export const recentFirst = () => Type.Optional(Type.Boolean({ description: "Return newest-first. Only an explicit false returns oldest-first. Defaults to true." }));
 /** Role filter. `developer` is the known author for this extension's own custom entries. */
-export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool_call"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the item's role. Exactly six: \"user\" and \"assistant\" are a message's visible text (assistant text never contains tool calls); \"tool_call\" is one tool invocation (tool_name set, content = the call's JSON arguments); \"tool\" is one tool run's output (tool_name set); \"system\" is a native Pi compaction summary; \"developer\" is an entry this extension authored (boot, guidance, warning, continuation messages, reset-window compaction summaries, any pi-context/* entry)." });
+export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool_call"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the item's role. Exactly six: \"user\" and \"assistant\" are a message's visible text (assistant text never contains tool calls); \"tool_call\" is one tool invocation (tool_name set, content = the call's JSON arguments); \"tool\" is one tool run's output (tool_name set); \"system\" is a native Pi compaction or branch summary; \"developer\" is an entry this extension authored (boot, guidance, warning, continuation messages, or any pi-context/* custom message)." });
 
 /** Search query parameter: one literal, or several literals combined with OR. */
 export const searchQuery = () => Type.Union([Type.String(), Type.Array(Type.String(), { minItems: 1 })]);
@@ -23,4 +23,3 @@ export function searchQueries(query: unknown): string[] {
 	if (candidates.some((candidate) => candidate === "")) throw new Error("query strings must be non-empty: an empty query matches everything");
 	return candidates as string[];
 }
-

package/dist/src/budget.js

@@ -1,65 +0,0 @@
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { GUIDANCE_TYPE, WARNING_TYPE } from "./protocol.js";
-import { thresholdsFor, resetThresholds } from "./thresholds.js";
-import { currentWindowId, hasWindowMessage } from "./history.js";
-import { tokenBudgetGuidance } from "./prompts.js";
-import { output } from "./tool-output.js";
-/** Remaining tokens in the current context window, or null when Pi has no usage estimate. */
-export function remainingTokens(ctx) {
-    const usage = ctx.getContextUsage();
-    return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
-}
-export function registerBudget(pi, isEnabled) {
-    let guidancePersistedInWindow;
-    pi.on("session_start", (_event, ctx) => { guidancePersistedInWindow = undefined; resetThresholds(); thresholdsFor(ctx); });
-    pi.on("session_tree", () => { guidancePersistedInWindow = undefined; resetThresholds(); });
-    pi.on("context", (_event, ctx) => {
-        if (!isEnabled() || hasWindowMessage(ctx, GUIDANCE_TYPE))
-            return undefined;
-        // The early reminder persists once per window the first time remaining crosses
-        // reserve+margin. It never edits the outgoing request.
-        const remaining = remainingTokens(ctx);
-        if (remaining === null)
-            return undefined;
-        const windowId = currentWindowId(ctx);
-        const { reminder, reserve, warning } = thresholdsFor(ctx);
-        // The final warning owns the deep band: when it has fired (or is due now),
-        // the shallow reminder would only repeat the same instruction closer to
-        // the wipe, at a worse position. See warning.ts.
-        if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE))
-            return undefined;
-        if (remaining <= reminder && guidancePersistedInWindow !== windowId) {
-            guidancePersistedInWindow = windowId;
-            // Persist once per window — no transient copy. A transient bridge would
-            // cover the crossing request, but history would record the reminder after
-            // that request's assistant reply, so across the boundary the model would
-            // meet the same text twice at shifted positions. The reminder is an early
-            // warning, not a per-request instruction: arriving from the next request
-            // on (sendMessage defers safely to end of turn while streaming, queueing
-            // instead of splitting a tool call/result pair) costs nothing, and the
-            // model's view stays identical to recorded history, Codex-style.
-            // The persisted copy stays out of the TUI (display: false); one ephemeral
-            // notify tells the user instead — visible to the human, invisible to the
-            // model, and never recorded, so history and the model's view don't diverge.
-            // The model-facing count ends at the warning line: what lies below is the
-            // runway, invisible by design. The human's notify keeps the honest count.
-            const left = Math.max(0, remaining - warning);
-            pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(left), display: false }, { triggerTurn: false });
-            ctx.ui.notify(`pi-context: context budget low (${Math.max(0, remaining - reserve)} tokens before reserve) — checkpoint reminder recorded for the model, kept out of the chat view.`, "warning");
-        }
-        return undefined;
-    });
-    pi.registerTool(defineTool({
-        name: "get_context_remaining",
-        label: "Get context remaining",
-        description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
-        parameters: Type.Object({}, { additionalProperties: false }),
-        async execute(_id, _params, _signal, _update, ctx) {
-            // The countdown the model sees ends at the warning line (reserve + runway);
-            // the runway below it is overdraft the model never sees. See protocol.ts.
-            const remaining = remainingTokens(ctx);
-            return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx).warning) });
-        },
-    }));
-}

package/dist/src/notes/model.js

@@ -1,101 +0,0 @@
-import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
-export function assertVirtualPath(value) {
-    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;
-}
-/**
- * Minimal glob over virtual note paths: `*` matches any run within a segment (never
- * `/`), `**` matches any run across segments (a leading double-star followed by a
- * slash also matches zero segments, so it covers the root too), `?` matches exactly
- * one non-`/` character. Everything else is literal and the match is anchored to the
- * whole path.
- */
-export function globToRegExp(pattern) {
-    let source = "^";
-    for (let index = 0; index < pattern.length; index++) {
-        const char = pattern[index];
-        if (char === "*") {
-            if (pattern[index + 1] === "*") {
-                const followedBySlash = pattern[index + 2] === "/";
-                source += followedBySlash ? "(?:[^]*\\/)?" : "[^]*";
-                index += followedBySlash ? 2 : 1;
-            }
-            else {
-                source += "[^/]*";
-            }
-        }
-        else {
-            source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
-        }
-    }
-    return new RegExp(`${source}$`);
-}
-/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
-export function assertGlobPattern(value) {
-    if (value === undefined || value === null || value === "")
-        return undefined;
-    if (typeof value !== "string")
-        throw new Error("glob pattern must be a string");
-    if (value.includes("\0") || value.includes("\\"))
-        throw new Error("glob pattern must not contain NUL or backslashes");
-    return value;
-}
-/** Replays only pi-context note operations from session custom entries. */
-function isNoteOperation(data) {
-    if (typeof data !== "object" || data === null)
-        return false;
-    const op = data;
-    return ((op.op === "write" || op.op === "append") &&
-        typeof op.path === "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()));
-}
-export function notesFromSession(ctx) {
-    const files = new Map();
-    for (const entry of ctx.sessionManager.getBranch()) {
-        if (entry.type !== "custom" || entry.customType !== NOTE_TYPE || !isNoteOperation(entry.data))
-            continue;
-        const op = entry.data;
-        try {
-            assertVirtualPath(op.path);
-        }
-        catch {
-            continue;
-        }
-        const previous = files.get(op.path);
-        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) : 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;
-}
-const pad2 = (value) => String(value).padStart(2, "0");
-/**
- * Format epoch milliseconds as an ISO 8601 string in the host's local time zone with an
- * explicit numeric offset (e.g. 2026-09-15T17:31:45.392+08:00). A UTC host renders
- * "+00:00"; the "Z" designator is never used, and Date.parse round-trips the value.
- */
-export function localIso(epochMs) {
-    const date = new Date(epochMs);
-    const offsetMinutes = -date.getTimezoneOffset();
-    const absOffset = Math.abs(offsetMinutes);
-    const offset = `${offsetMinutes < 0 ? "-" : "+"}${pad2(Math.floor(absOffset / 60))}:${pad2(absOffset % 60)}`;
-    const wallClock = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}`;
-    return `${wallClock}${offset}`;
-}

package/dist/src/prompts.js

@@ -1,88 +0,0 @@
-import { historyFromSession } from "./history.js";
-import { listNotes } from "./notes/store.js";
-import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_PERSONAL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
-/** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
-function identityBlock(agentName, firstWindowId, currentWindowId, previousWindowId) {
-    const lines = [
-        `Agent name: ${agentName}`,
-        `First context window id: ${firstWindowId}`,
-        `Current context window id: ${currentWindowId}`,
-    ];
-    if (previousWindowId)
-        lines.push(`Previous context window id: ${previousWindowId}`);
-    return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
-}
-function relativeTime(timestamp, now) {
-    const seconds = Math.trunc((timestamp - now) / 1000);
-    const [unit, size] = [["d", 86400], ["h", 3600], ["m", 60], ["s", 1]]
-        .find(([unit, size]) => Math.abs(seconds) >= size || unit === "s");
-    const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
-    return seconds > 0 ? `in ${amount}` : `${amount} ago`;
-}
-/**
- * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the personal and
- * project homes are both injected, broadest first; stale maps are skipped per home, and the
- * session home is never peeked — a session MAP.md is an ordinary note. The pocket then lists
- * recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT / POCKET_PROJECT_LIMIT /
- * POCKET_PERSONAL_LIMIT), most-recently-updated first within each home, one metadata line
- * each: address, line count, UTF-8 byte count, relative update time at window open. Bodies never render
- * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
- */
-function notesIndex(ctx) {
-    const sections = [];
-    // Map residency ("地图在场"): scope-native maps, both fresh ones injected broadest-first.
-    // A session MAP.md is an ordinary note, never resident; stale maps skip independently.
-    for (const scope of ["personal", "project"]) {
-        const toc = listNotes(ctx, { scope }).find((row) => row.path === "MAP.md");
-        if (toc && !toc.meta.stale) {
-            if (toc.body.length > 0)
-                sections.push(toc.body);
-        }
-    }
-    // listNotes is most-recently-updated first within each home. Per-home quotas keep session
-    // churn from evicting project or personal notes; maps never take pocket seats.
-    const recentNotes = [
-        ...listNotes(ctx, { scope: "session" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
-        ...listNotes(ctx, { scope: "project" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
-        ...listNotes(ctx, { scope: "personal" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PERSONAL_LIMIT),
-    ];
-    if (recentNotes.length > 0) {
-        const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_PERSONAL_LIMIT} from personal). A note's content never appears here, so its name has to say what the note is about:`];
-        const now = Date.now();
-        for (const row of recentNotes) {
-            lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, now)})`);
-        }
-        sections.push(lines.join("\n"));
-    }
-    return sections.join("\n\n");
-}
-function notesHomeBlock() {
-    return "Notes_* addresses have three homes: bare <vpath> is this session, @project/<vpath> is this project, and @personal/<vpath> is the human's cross-project home. @ means leaving home; there is no cross-home fallback. Any other note is a plain file — use the file tools.";
-}
-/**
- * Assemble the static, once-per-window boot block: the reset line for resets, the
- * <context_window> identity block, the recent-notes index at window-open time, and
- * the <context_window_protocol> teaching block. Nothing here is re-injected, so the
- * head of the window stays cache-stable.
- */
-export function bootBlock(ctx, currentId, previousId, resetLine) {
-    const firstId = historyFromSession(ctx)[0]?.windowId ?? currentId;
-    const parts = [];
-    if (resetLine)
-        parts.push(RESET_SUMMARY);
-    parts.push(identityBlock(ctx.sessionManager.getSessionName() ?? "root", firstId, currentId, previousId));
-    parts.push(notesHomeBlock());
-    const index = notesIndex(ctx);
-    if (index)
-        parts.push(index);
-    parts.push(PROTOCOL_BLOCK);
-    return parts.join("\n\n");
-}
-/**
- * Codex-equivalent low-budget reminder. The measured remaining count is frozen into
- * the text at the crossing that fires it, so each persisted copy is a snapshot true
- * at write time; get_context_remaining remains the live source for the current figure.
- */
-export function tokenBudgetGuidance(remaining) {
-    return `${GUIDANCE_OPEN_TAG}\nYour brain is almost out of room — ${remaining} tokens left, and then your memory gets wiped. The wipe is automatic: there is no final turn to write then. Grab the notebook now — the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Replacing an older checkpoint? Mark it stale. Then call wipe_memory yourself — anything you do after the checkpoint isn't in it.\n${GUIDANCE_CLOSE_TAG}`;
-}