@astrosheep/pi-context 0.20.0 → 0.21.0

package/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 
@@ -53,7 +53,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			if (invalid) return output({ error: invalid, role: params.role, tool_name: params.tool_name });
 			const badWindow = unknownWindowId(ctx, params);
 			if (badWindow) return output({ error: badWindow.message, window_id: params.window_id, known_windows: badWindow.known });
-			const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
+			const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? HISTORY_PREVIEW_CHARS));
 			return output(page(items, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
 		},
 	}));
@@ -62,7 +62,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		name: "history_read",
 		label: "History read item",
 		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
-		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })), window_id: Type.String() }, { additionalProperties: false }),
+		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })), window_id: Type.String() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			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" });
@@ -72,7 +72,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
 				return output({ error: `offset_chars ${params.offset_chars} is past the end: the item has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, window_id: item.windowId, item_id: item.itemId, offset_chars: params.offset_chars, total_chars: totalChars });
 			}
-			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+			const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
 			return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
 				const { content, ...cursor } = window;
 				return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
@@ -93,7 +93,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			const queries = searchQueries(params.query);
 			const matching = filteredItems(ctx, params)
 				.filter((item) => queries.some((query) => item.content.includes(query)))
-				.map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? 1200), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
+				.map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? HISTORY_PREVIEW_CHARS), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
 			return output(page(matching, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
 		},
 	}));

package/src/history.ts

@@ -2,6 +2,7 @@ import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { SessionReader } from "./session-reader.js";
 import { RESET_V2 } from "./protocol.js";
+import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
 
 type HistoryItem = {
 	windowId: string;
@@ -29,9 +30,9 @@ function isTextContent(part: unknown): part is TextContent {
 	return typeof part === "object" && part !== null && (part as TextContent).type === "text" && typeof (part as TextContent).text === "string";
 }
 
-function contentText(content: string | unknown[]): string {
+export function contentText(content: unknown): string {
 	if (typeof content === "string") return content;
-	return content.filter(isTextContent).map((part) => part.text).join("\n");
+	return Array.isArray(content) ? content.filter(isTextContent).map((part) => part.text).join("\n") : "";
 }
 
 function mapRole(role: AgentMessage["role"]): HistoryItem["role"] | undefined {
@@ -102,14 +103,19 @@ export function resetV2WindowId(details: unknown): string | undefined {
 }
 
 /** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
-function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
+export function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
 	return resetV2WindowId(entry.details) ?? `pcw:${sessionId.slice(0, 8)}:${entry.id}`;
 }
 
+/** Mint the durable identity of a session's root history window. */
+export function rootWindowId(sessionId: string): string {
+	return `pcw:${sessionId.slice(0, 8)}:root`;
+}
+
 /** Build durable, on-demand history directly from every entry on the current session branch. */
 export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	const sessionId = ctx.sessionManager.getSessionId();
-	let window: HistoryWindow = { windowId: `pcw:${sessionId.slice(0, 8)}:root`, items: [] };
+	let window: HistoryWindow = { windowId: rootWindowId(sessionId), items: [] };
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type === "compaction") {
@@ -153,7 +159,7 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	return windows;
 }
 
-export function visibleItem(item: HistoryItem, maxChars = 1200) {
+export function visibleItem(item: HistoryItem, maxChars = HISTORY_PREVIEW_CHARS) {
 	const characters = Array.from(item.content);
 	const truncated = characters.length > maxChars;
 	return {
@@ -230,6 +236,5 @@ export function currentWindowId(ctx: SessionReader): string {
 		const entry = branch[i];
 		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
 	}
-	return `pcw:${sessionId.slice(0, 8)}:root`;
+	return rootWindowId(sessionId);
 }
-

package/src/index.ts

@@ -1,14 +1,14 @@
 import { registerHistoryTools } from "./history-tools.js";
-import { registerMemoryTools } from "./memory/tools.js";
-import { registerBudget, deriveThresholds, mergePiContextSettings } from "./budget.js";
+import { registerNotesTools } from "./notes/tools.js";
+import { registerBudget } from "./budget.js";
 import { output } from "./tool-output.js";
-export { deriveThresholds, mergePiContextSettings };
+import { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
 import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
-import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId } from "./history.js";
-import { assertVirtualPath } from "./notes.js";
+import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId, rootWindowId, windowIdOf } from "./history.js";
+import { assertVirtualPath } from "./notes/model.js";
 import { bootBlock } from "./prompts.js";
 export { historyFromSession } from "./history.js";
-export { notesFromSession } from "./notes.js";
+export { notesFromSession } from "./notes/model.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
 import { registerWarning } from "./warning.js";
 import { randomUUID } from "node:crypto";
@@ -25,8 +25,7 @@ export default function piContext(pi: ExtensionAPI) {
 		// The root window has no compaction entry to carry the boot block, so persist
 		// it once as a hidden custom message. Reset windows already carry theirs at
 		// position 0 in the compaction summary, so a resumed session adds nothing.
-		const sessionId = ctx.sessionManager.getSessionId();
-		const rootId = `pcw:${sessionId.slice(0, 8)}:root`;
+		const rootId = rootWindowId(ctx.sessionManager.getSessionId());
 		if (currentWindowId(ctx) !== rootId || hasWindowMessage(ctx, BOOT_TYPE)) return;
 		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: false }, { triggerTurn: false });
 	});
@@ -48,7 +47,7 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 
 	registerHistoryTools(pi);
-	registerMemoryTools(pi);
+	registerNotesTools(pi);
 
 	pi.registerTool(defineTool({
 		name: "new_context",
@@ -70,15 +69,15 @@ export default function piContext(pi: ExtensionAPI) {
 		},
 		onReset: (entryId) => pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entryId }),
 		buildReset: (event, ctx, explicit) => {
-			const session8 = ctx.sessionManager.getSessionId().slice(0, 8);
+			const sessionId = ctx.sessionManager.getSessionId();
 			// Window IDs are independent of Pi entry IDs. Avoid reusing a window
 			// identity already present on this branch.
 			const windows = historyFromSession(ctx);
 			const usedIds = new Set(windows.map((window) => window.windowId));
-			let minted = randomUUID().slice(0, 8);
-			while (usedIds.has(`pcw:${session8}:${minted}`)) minted = randomUUID().slice(0, 8);
-			const windowId = `pcw:${session8}:${minted}`;
-			const previousId = windows[windows.length - 1]?.windowId ?? `pcw:${session8}:root`;
+			let minted = { id: randomUUID().slice(0, 8) };
+			while (usedIds.has(windowIdOf(sessionId, minted))) minted = { id: randomUUID().slice(0, 8) };
+			const windowId = windowIdOf(sessionId, minted);
+			const previousId = windows[windows.length - 1]?.windowId ?? rootWindowId(sessionId);
 			// The reset marker stays as firstKeptEntryId; it no longer names the window.
 			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: explicit });
 			const markerId = ctx.sessionManager.getLeafId();

package/src/notes/address.ts

@@ -0,0 +1,33 @@
+import { assertVirtualPath } from "./model.js";
+import type { Scope } from "./paths.js";
+
+export type NoteAddress = { scope: Scope; path: string };
+
+const ADDRESS_FORMS = "legal prefixes are @project/ and @global/; bare names are the session home";
+
+/**
+ * Decode the one public note address into its physical home and virtual path. This is a
+ * tool-boundary rule: replay paths keep using assertVirtualPath directly and are untouched.
+ */
+export function assertAddress(value: unknown): NoteAddress {
+	if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	let scope: Scope = "session";
+	let path = value;
+	if (value.startsWith("@project/")) {
+		scope = "project";
+		path = value.slice("@project/".length);
+	} else if (value.startsWith("@global/")) {
+		scope = "global";
+		path = value.slice("@global/".length);
+	} else if (value.startsWith("@")) {
+		throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	}
+	if (path.includes("@")) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	assertVirtualPath(path);
+	return { scope, path };
+}
+
+/** Render a virtual path in its one unambiguous public address form. */
+export function addressFor(scope: Scope, path: string): string {
+	return scope === "session" ? path : `@${scope}/${path}`;
+}

package/src/{memory → notes}/frontmatter.ts

@@ -1,4 +1,4 @@
-import { localIso } from "../notes.js";
+import { localIso } from "./model.js";
 import type { Scope } from "./paths.js";
 
 export type NoteStatus = "active" | "superseded" | "pending" | "archived";
@@ -30,7 +30,7 @@ const ORIGINS: readonly Origin[] = ["user", "self", "external"];
 const STATUSES: readonly NoteStatus[] = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"] as const;
 /** Emission order, exactly the Design's key list. */
-const KNOWN_KEYS = ["scope", "origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
+const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
 
 export function isScope(value: unknown): value is Scope {
 	return typeof value === "string" && (SCOPES as readonly string[]).includes(value);
@@ -140,7 +140,9 @@ export function serializeNote(meta: NoteMeta, body: string): string {
 		else lines.push(`${key}: ${yamlScalar(value)}`);
 	}
 	for (const key of Object.keys(meta)) {
-		if ((KNOWN_KEYS as readonly string[]).includes(key)) continue;
+		// scope is a legacy on-disk field. Store callers derive it from the home's location,
+		// but serialization intentionally drops it on the next write.
+		if (key === "scope" || (KNOWN_KEYS as readonly string[]).includes(key)) continue;
 		if (meta[key] === undefined) continue;
 		lines.push(`${key}: ${yamlScalar(meta[key])}`);
 	}

package/src/{notes.ts → notes/model.ts}

@@ -1,5 +1,5 @@
-import type { SessionReader } from "./session-reader.js";
-import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
+import type { SessionReader } from "../session-reader.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
 
 export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
 export type NoteOperation = {

package/src/{memory → notes}/paths.ts

@@ -12,6 +12,11 @@ export function notesRoot(): string {
 	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
 }
 
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home = notesRoot()): string {
+	return join(home, "pi", "session");
+}
+
 /**
  * Absolute git root for `cwd`, walking upward until a directory holds a `.git` entry.
  * No git root yields undefined, which projectKey then replaces with the cwd itself.
@@ -43,7 +48,7 @@ function sessionId(ctx: ExtensionContext): string {
 export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
 	if (scope === "global") return join(notesRoot(), "global");
 	if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
-	return join(notesRoot(), "pi", "session", sessionId(ctx));
+	return join(sessionHomesRoot(), sessionId(ctx));
 }
 
 /**

package/src/{memory → notes}/store.ts

@@ -3,10 +3,12 @@ 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 "../notes.js";
+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 { earliestMatchOffsetChars } from "../tool-output.js";
 
 export type { NoteMeta, Origin, Scope };
 
@@ -26,9 +28,9 @@ export class NoteError extends Error {
 	}
 }
 
-export type NoteRow = { path: string; meta: NoteMeta; sizeBytes: number };
+export type NoteRow = { address: string; scope: Scope; path: string; meta: NoteMeta; body: string; sizeBytes: number };
 export type NoteMatch = { line: number; text: string; offsetChars: number };
-export type NoteSearchRow = { path: string; scope: Scope; meta: NoteMeta; matches: NoteMatch[] };
+export type NoteSearchRow = { address: string; scope: Scope; path: string; meta: NoteMeta; matches: NoteMatch[] };
 
 const SCOPE_ORDER: readonly Scope[] = ["session", "project", "global"];
 
@@ -42,22 +44,6 @@ function assertOrigin(value: unknown): Origin {
 	return value;
 }
 
-function scopeList(scope?: unknown): Scope[] {
-	if (scope === undefined || scope === null) return [...SCOPE_ORDER];
-	return [assertScope(scope)];
-}
-
-type Resolved = { scope: Scope; path: string; raw: string };
-
-/** First existing file by precedence session → project → global, or only `scope` when given. */
-function resolve(ctx: ExtensionContext, vpath: string, scope?: unknown): Resolved | undefined {
-	for (const candidate of scopeList(scope)) {
-		const path = physicalPath(candidate, vpath, ctx);
-		if (existsSync(path)) return { scope: candidate, path, raw: readFileSync(path, "utf8") };
-	}
-	return undefined;
-}
-
 /** Recursively list `.md` files under `dir` as forward-slash virtual paths relative to `base`. */
 function walkMarkdown(dir: string, base = dir): string[] {
 	let entries: Dirent[];
@@ -160,7 +146,7 @@ export function writeNote(ctx: ExtensionContext, vpath: string, body: string, op
 }
 
 export type EditOperation = { oldText: string; newText: string };
-export type EditOptions = { scope?: Scope; origin?: Origin; stale?: boolean; replaceAll?: boolean };
+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 } {
@@ -177,17 +163,19 @@ export function updateNoteMeta(ctx: ExtensionContext, vpath: string, scope: Scop
 	return { meta, body: parsed.body };
 }
 
-/** Apply body-only edits against one snapshot, then optionally move via the scope/origin/stale setters. */
-export function editNote(ctx: ExtensionContext, vpath: string, edits: EditOperation[] | undefined, opts: EditOptions = {}): { meta: NoteMeta; applied: number; resolved_scope: Scope; diff: string } {
+/** 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 } {
 	assertVirtualPath(vpath);
 	assertWritablePath(vpath);
 	const operations = edits ?? [];
-	if (operations.length === 0 && opts.scope === undefined && opts.origin === undefined && opts.stale === undefined) {
-		throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of scope, origin, stale");
+	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 found = resolve(ctx, vpath);
-	if (!found) throw new NoteError("not_found", "note not found");
-	const { meta, body } = parseNote(found.raw);
+	const path = physicalPath(scope, vpath, ctx);
+	if (!existsSync(path)) throw new NoteError("not_found", "note not found");
+	const raw = readFileSync(path, "utf8");
+	const { meta, body } = parseNote(raw);
+	meta.scope = scope;
 	// Snapshot the pre-edit frontmatter so the diff can name exactly what the setters changed.
 	const beforeMeta: NoteMeta = { ...meta };
 	// Every edit runs against this one snapshot; nothing is written until all of them succeed,
@@ -203,79 +191,65 @@ export function editNote(ctx: ExtensionContext, vpath: string, edits: EditOperat
 		if (lines.length > 1 && !opts.replaceAll) {
 			throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { line_numbers: lines, edit_index: index });
 		}
-		next = opts.replaceAll ? next.split(oldText).join(newText) : next.replace(oldText, newText);
+		// Single replacement is positional splicing, never String.replace: user text must be
+		// inserted byte-for-byte, without $-pattern substitution ($&, $`, $', $1, $$).
+		if (opts.replaceAll) {
+			next = next.split(oldText).join(newText);
+		} else {
+			const matchIndex = next.indexOf(oldText);
+			next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+		}
 	});
-	const destScope = opts.scope === undefined ? found.scope : assertScope(opts.scope);
 	if (opts.origin !== undefined) meta.origin = assertOrigin(opts.origin);
 	if (opts.stale !== undefined) meta.stale = opts.stale;
-	meta.scope = destScope;
 	meta.updated_at = Date.now();
-	const dest = physicalPath(destScope, vpath, ctx);
-	const moving = dest !== found.path;
-	if (moving && existsSync(dest)) {
-		throw new NoteError("target_exists", `a note already exists at ${vpath} in scope ${destScope}; the move was refused and both files are unchanged`);
-	}
 	const serialized = serializeNote(meta, next);
 	assertSerializedSize(serialized);
 	// pi-edit-style diff: body only for a content edit, frontmatter only for a metadata-only
-	// update, one combined file diff when both moved.
+	// update, one combined file diff when both change.
 	const bodyChanged = body !== next;
-	const metadataChanged = beforeMeta.scope !== meta.scope || beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+	const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
 	const diff = bodyChanged && metadataChanged
-		? generateDiffString(found.raw, serialized).diff
+		? generateDiffString(raw, serialized).diff
 		: bodyChanged
 			? generateDiffString(body, next).diff
 			: metadataChanged
 				? generateDiffString(frontmatterOf(beforeMeta), frontmatterOf(meta)).diff
 				: "";
-	atomicWrite(dest, serialized);
-	if (moving) rmSync(found.path);
-	return { meta, applied: operations.length, resolved_scope: found.scope, diff };
+	atomicWrite(path, serialized);
+	return { meta, applied: operations.length, resolved_scope: scope, diff };
 }
 
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx: ExtensionContext, vpath: string, opts: { scope?: Scope } = {}): { meta: NoteMeta; body: string; resolvedScope: Scope } | undefined {
+export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; resolvedScope: Scope } | undefined {
 	assertVirtualPath(vpath);
-	const found = resolve(ctx, vpath, opts.scope);
-	if (!found) return undefined;
+	const path = physicalPath(scope, vpath, ctx);
+	if (!existsSync(path)) return undefined;
 	const now = Date.now();
-	const { meta, body } = parseNote(found.raw, now);
-	meta.scope = found.scope;
+	const { meta, body } = parseNote(readFileSync(path, "utf8"), now);
+	meta.scope = scope;
 	// Only the two access keys move; updated_at and every other key keep their bytes.
 	meta.last_accessed = now;
 	meta.access_count = (typeof meta.access_count === "number" ? meta.access_count : 0) + 1;
-	atomicWrite(found.path, serializeNote(meta, body));
-	return { meta, body, resolvedScope: found.scope };
-}
-
-/** The scope that holds `vpath` first by precedence, without reading or mutating the file. */
-export function resolveNoteScope(ctx: ExtensionContext, vpath: string, scope?: Scope): { scope: Scope; path: string } | undefined {
-	const found = resolve(ctx, vpath, scope);
-	return found ? { scope: found.scope, path: found.path } : undefined;
-}
-
-/** Read a note's meta and body without the read side effect (used by the boot index). */
-export function peekNote(ctx: ExtensionContext, scope: Scope, vpath: string): { meta: NoteMeta; body: string } {
-	const path = physicalPath(scope, vpath, ctx);
-	const { meta, body } = parseNote(readFileSync(path, "utf8"));
-	meta.scope = scope;
-	return { meta, body };
+	atomicWrite(path, serializeNote(meta, body));
+	return { meta, body, resolvedScope: scope };
 }
 
-/** Merged rows across scopes, most recently updated first (path then scope break ties). */
+/** 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);
 	const rows: NoteRow[] = [];
-	for (const scope of scopeList(opts.scope)) {
+	for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
 		const root = scopeDir(scope, ctx);
 		for (const path of walkMarkdown(root)) {
-			if (matcher && !matcher.test(path)) continue;
+			const address = addressFor(scope, path);
+			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;
-			rows.push({ path, meta, sizeBytes: Buffer.byteLength(body, "utf8") });
+			rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
 		}
 	}
-	rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.path.localeCompare(b.path) || a.meta.scope.localeCompare(b.meta.scope));
+	rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.address.localeCompare(b.address));
 	return rows;
 }
 
@@ -283,28 +257,24 @@ export function listNotes(ctx: ExtensionContext, opts: { scope?: Scope; pattern?
 export function searchNotes(ctx: ExtensionContext, queries: string[], opts: { scope?: Scope; pattern?: string } = {}): NoteSearchRow[] {
 	const matcher = matcherFor(opts.pattern);
 	const rows: NoteSearchRow[] = [];
-	for (const scope of scopeList(opts.scope)) {
+	for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
 		const root = scopeDir(scope, ctx);
 		for (const path of walkMarkdown(root)) {
-			if (matcher && !matcher.test(path)) continue;
+			const address = addressFor(scope, path);
+			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;
 			let baseChars = 0;
 			const matches: NoteMatch[] = [];
 			for (const [index, line] of body.split("\n").entries()) {
 				if (queries.some((query) => line.includes(query))) {
-					let earliest = -1;
-					for (const query of queries) {
-						const found = line.indexOf(query);
-						if (found >= 0 && (earliest < 0 || found < earliest)) earliest = found;
-					}
-					matches.push({ line: index + 1, text: line, offsetChars: baseChars + (earliest <= 0 ? 0 : Array.from(line.slice(0, earliest)).length) });
+					matches.push({ line: index + 1, text: line, offsetChars: baseChars + earliestMatchOffsetChars(line, queries) });
 				}
 				baseChars += Array.from(line).length + 1;
 			}
-			if (matches.length > 0) rows.push({ path, scope, meta, matches });
+			if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
 		}
 	}
-	rows.sort((a, b) => a.path.localeCompare(b.path) || a.scope.localeCompare(b.scope));
+	rows.sort((a, b) => a.address.localeCompare(b.address));
 	return rows;
 }

package/src/notes/tools.ts

@@ -0,0 +1,132 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { localIso } from "./model.js";
+import { characterWindowHeader, DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
+import { assertAddress } from "./address.js";
+import { serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+
+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 `@global/<vpath>` for the global home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@global/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
+
+function wireMeta(meta: NoteMeta): Record<string, unknown> {
+	return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
+}
+
+function failure(error: unknown) {
+	if (error instanceof NoteError) {
+		const payload: Record<string, unknown> = { error: error.message };
+		if (error.line_numbers) payload.line_numbers = error.line_numbers;
+		if (error.edit_index !== undefined) payload.edit_index = error.edit_index;
+		return output(payload);
+	}
+	throw error;
+}
+
+export function registerNotesTools(pi: ExtensionAPI) {
+	pi.registerTool(defineTool({
+		name: "notes_write", label: "Notes write",
+		description: `Create or replace a note as a real markdown file, and name it for what it holds: a fresh window sees only an index entry, never the note itself. ${ADDRESS_DESCRIPTION} Keep notes small and split by topic — by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving created_at and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.`,
+		parameters: Type.Object({ address: Type.String(), content: Type.String(), origin: ORIGIN, stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
+		async execute(_id, params, _signal, _update, ctx) {
+			const content = params.content;
+			try {
+				const destination = assertAddress(params.address);
+				const { meta } = writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				return output({ address: params.address, scope: meta.scope, size_bytes: Buffer.byteLength(stripLeadingFrontmatter(content), "utf8"), meta: wireMeta(meta) });
+			} catch (error) { return failure(error); }
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_edit", label: "Notes edit",
+		description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries resolved_scope and a diff of what changed.`,
+		parameters: Type.Object({ address: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), origin: ORIGIN, stale: Type.Optional(Type.Boolean()), replace_all: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
+		async execute(_id, params, _signal, _update, ctx) {
+			try {
+				const destination = assertAddress(params.address);
+				const { meta, applied, resolved_scope, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				return output({ address: params.address, applied, resolved_scope, diff, meta: wireMeta(meta) });
+			} catch (error) { return failure(error); }
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_read", label: "Notes read",
+		description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw frontmatter + body behind a one-line [bracketed] header naming the address, the resolved offset, the delivered char range, and the resume cursor.`,
+		parameters: Type.Object({ address: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })) }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			let note: ReturnType<typeof readNote>;
+			try {
+				const destination = assertAddress(params.address);
+				note = readNote(ctx, destination.path, destination.scope);
+			} catch (error) { return failure(error); }
+			if (!note) return output({ error: "note not found", address: params.address });
+			const text = serializeNote(note.meta, note.body);
+			const totalChars = Array.from(text).length;
+			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, address: params.address, offset_chars: params.offset_chars, total_chars: totalChars });
+			const created_at = localIso(note.meta.created_at);
+			const updated_at = localIso(note.meta.updated_at);
+			const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
+			return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...rest } = window;
+				return outputRaw(characterWindowHeader(params.address, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { address: params.address, scope: note.resolvedScope, ...rest, limit_chars, created_at, updated_at });
+			}, (result) => withinTextBudget(result.content[0].text));
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "notes_list", label: "Notes list",
+		description: `List note files as rows carrying address, scope, origin, status, stale, size_bytes, created_at, and updated_at, 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.`,
+		parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			let rows: ReturnType<typeof listNotes>;
+			try { rows = listNotes(ctx, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
+			const files: Array<{ address: string; scope: string; origin: Origin; status: string; stale: boolean; size_bytes: number; created_at: string; updated_at: string; address_truncated?: boolean }> = rows.map((row) => ({ address: row.address, scope: row.scope, origin: row.meta.origin, status: row.meta.status, stale: row.meta.stale, size_bytes: row.sizeBytes, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at) }));
+			return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
+				if (fits(file)) return file;
+				const address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
+				return { ...file, address, address_truncated: true };
+			}));
+		},
+	}));
+
+	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 and derived scope. 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 (the body-absolute code-point offset of the earliest match).`,
+		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);
+			let rows: ReturnType<typeof searchNotes>;
+			try { rows = searchNotes(ctx, queries, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
+			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
+			const result: Array<{ address: string; scope: string; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; address_truncated?: boolean }> = rows.map((row) => {
+				const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, total_chars: Array.from(match.text).length, offset_chars: match.offsetChars }));
+				return { address: row.address, scope: row.scope, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at), matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+			});
+			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
+				if (fits(file)) return file;
+				const matches = file.matches;
+				let low = 0;
+				let high = matches.length;
+				while (low < high) {
+					const mid = Math.ceil((low + high) / 2);
+					if (mid >= 1 && fits({ ...file, matches: matches.slice(0, mid) })) low = mid;
+					else high = mid - 1;
+				}
+				if (low >= 1) return { ...file, matches: matches.slice(0, low) };
+				const first = matches[0]!;
+				const fitted = (text: string): (typeof result)[number] => ({ ...file, matches: [{ ...first, text, truncated: true }] });
+				const text = prefixFit(first.text, (candidate) => fits(fitted(candidate)));
+				const prefix = fitted(text);
+				if (fits(prefix)) return prefix;
+				const address = middleTruncate(prefix.address, (candidate) => fits({ ...prefix, address: candidate, address_truncated: true }));
+				return { ...prefix, address, address_truncated: true };
+			};
+			return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
+		},
+	}));
+}