@astrosheep/pi-context 0.24.0 → 0.25.1

package/src/notes/paths.ts

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-export type Scope = "session" | "project" | "personal";
+export type Scope = "session" | "project" | "human" | "agent" | "model";
 
 /** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
 export function notesRoot(): string {
@@ -44,13 +44,70 @@ function sessionId(ctx: ExtensionContext): string {
 	return ctx.sessionManager.getSessionId();
 }
 
-/** Absolute directory holding every note of one scope. */
-export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
-	if (scope === "personal") return join(notesRoot(), "personal");
+/** The one legal home-name shape: lowercase [a-z0-9-] runs separated by single dashes. */
+export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * Identity slugs: one declared name per home, never detected from prompt content.
+ * `PI_NOTES_AGENT` declares who is running (default "root"); the model slug derives
+ * from the live model id, provider prefix stripped. Both slugified to [a-z0-9-].
+ */
+export function slugify(value: string): string {
+	const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug.length > 0 ? slug : "root";
+}
+
+/** The current agent's home name: the launch-declared identity, defaulting to "root". */
+export function agentSlug(_ctx: ExtensionContext): string {
+	return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+
+/** The current model's home name, live-resolved from ctx.model; "default" when unknown. */
+export function modelSlug(ctx: ExtensionContext): string {
+	const id = ctx.model?.id;
+	if (!id) return "default";
+	return slugify(id.split("/").pop() ?? id);
+}
+
+/**
+ * Absolute directory holding every note of one scope. `who` names an agent or model
+ * home absolutely; omitted, the current one resolves (agent from PI_NOTES_AGENT,
+ * model live from ctx.model).
+ */
+export function scopeDir(scope: Scope, ctx: ExtensionContext, who?: string): string {
+	if (scope === "human") return join(notesRoot(), "human");
 	if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
+	if (scope === "agent") return join(notesRoot(), "agents", who ?? agentSlug(ctx));
+	if (scope === "model") return join(notesRoot(), "models", who ?? modelSlug(ctx));
 	return join(sessionHomesRoot(), sessionId(ctx));
 }
 
+/**
+ * One-time migration of the pre-v0.25 `personal/` home to `human/`. Runs at extension
+ * activation; returns a warning string when both directories exist (no auto-merge),
+ * undefined otherwise. Old note bodies are history, not addresses, and stay untouched.
+ */
+export function migrateLegacyHomes(home = notesRoot()): string | undefined {
+	const legacy = join(home, "personal");
+	const modern = join(home, "human");
+	if (!existsSync(legacy)) return undefined;
+	if (existsSync(modern)) return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+	renameSync(legacy, modern);
+	return undefined;
+}
+
+/** Every existing home directory of the agents/ or models/ namespace, as slugs. */
+export function namespaceSlugs(namespace: "agents" | "models", home = notesRoot()): string[] {
+	try {
+		return readdirSync(join(home, namespace), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
 /**
  * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit
  * `.md` is kept as-is, so `a/b` and `a/b.md` name the same physical file.
@@ -60,6 +117,6 @@ export function noteFileName(vpath: string): string {
 }
 
 /** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
-export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext): string {
-	return join(scopeDir(scope, ctx), ...noteFileName(vpath).split("/"));
+export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext, who?: string): string {
+	return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
 }

package/src/notes/session-replay.ts

@@ -0,0 +1,53 @@
+import type { SessionReader } from "../session-reader.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
+import { assertVirtualPath } from "./address.js";
+
+export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
+export type NoteOperation = {
+	op: "write" | "append";
+	path: string;
+	// Both are optional on the wire so mark-only and explicit-revive operations replay:
+	// at least one of text/stale is present, enforced by the note tools and isNoteOperation.
+	text?: string;
+	stale?: boolean;
+	createdAt: number;
+	updatedAt: number;
+};
+
+/** Replays only pi-context note operations from session custom entries. */
+function isNoteOperation(data: unknown): data is NoteOperation {
+	if (typeof data !== "object" || data === null) return false;
+	const op = data as Partial<NoteOperation>;
+	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: SessionReader): Map<string, NoteFile> {
+	const files = new Map<string, NoteFile>();
+	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 as string) : previous!.text;
+		if (Buffer.byteLength(text, "utf8") > MAX_NOTE_BYTES) continue;
+		// Carrying text revives unless the call also marks stale; a mark-only op keeps its flag.
+		const stale = hasText ? op.stale ?? false : op.stale ?? previous!.stale;
+		files.set(op.path, { text, stale, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
+	}
+	return files;
+}

package/src/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 notes, `@self/<vpath>` for your own, and `@model/<vpath>` for the current model's. `@self` and `@model` mean whoever is running now. Any other `@` prefix, or `@` inside a vpath, is a hard error. There is no fallback across prefixes. Paths reject `..`, absolute paths, and backslashes.";
 
 function failure(error: unknown) {
 	if (error instanceof NoteError) {
@@ -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 prefixes: this session, @project/, @human/, @self/, and @model/.`,
 		parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			let rows: ReturnType<typeof listNotes>;
@@ -89,7 +89,7 @@ export function registerNotesTools(pi: ExtensionAPI) {
 
 	pi.registerTool(defineTool({
 		name: "notes_search", label: "Notes search",
-		description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} 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 prefixes as notes_list. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
 		parameters: Type.Object({ query: searchQuery(), pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const queries = searchQueries(params.query);

package/src/protocol.ts

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