@astrosheep/pi-context 0.25.2 → 0.26.1

package/src/pi/notes/adapter.ts

@@ -0,0 +1,44 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { NotesContext } from "../../notes/context.js";
+import { projectKey, slugify } from "../../notes/paths.js";
+
+/** Pi's default notes root; environment access stays on the host side of the library boundary. */
+export function notesRoot(): string {
+	const override = process.env.PI_NOTES_HOME;
+	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+
+/** Translate the current Pi runtime into a fresh, explicit identity snapshot. */
+export function agentSlug(_ctx: ExtensionContext): string {
+	return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+
+/** Pi's active model identity is resolved live so a mid-session switch retargets @model. */
+export function modelSlug(ctx: ExtensionContext): string {
+	const id = ctx.model?.id;
+	return id ? slugify(id.split("/").pop() ?? id) : "default";
+}
+
+/** Translate the current Pi runtime into one explicit notes identity snapshot. */
+export function notesContextFromPi(ctx: ExtensionContext, home = notesRoot()): NotesContext {
+	return {
+		home,
+		sessionId: ctx.sessionManager.getSessionId(),
+		projectKey: projectKey(ctx.cwd),
+		agent: agentSlug(ctx),
+		model: modelSlug(ctx),
+	};
+}
+
+/** One-time host activation migration from the legacy personal/ directory. */
+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;
+}

package/src/{notes → pi/notes}/session-replay.ts

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

package/src/{notes/notes-snapshot.ts → pi/notes/snapshot.ts}

@@ -1,5 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { listNotes, type NoteRow, type Scope } from "./store.js";
+import type { NotesContext } from "../../notes/context.js";
+import { createNotesStore, type NoteRow, type NotesQuery, type Scope } from "../../notes/index.js";
+import { notesContextFromPi } from "./adapter.js";
 
 const NOTES_HOMES = [
 	{ scope: "session", label: "this session" },
@@ -10,7 +12,7 @@ const NOTES_HOMES = [
 ] as const satisfies ReadonlyArray<{ scope: Scope; label: string }>;
 
 export type NotesHome = (typeof NOTES_HOMES)[number];
-export type NotesLoader = (ctx: ExtensionContext, scope: Scope) => NoteRow[];
+export type NotesLoader = (ctx: ExtensionContext, scope: Scope) => NoteRow[] | Promise<NoteRow[]>;
 export type NotesSnapshot = {
 	/** Wall-clock instant captured when this boot began; rendering never consults Date.now(). */
 	readonly openedAt: number;
@@ -18,17 +20,24 @@ export type NotesSnapshot = {
 	readonly unavailable: readonly NotesHome[];
 };
 
+function queryForScope(scope: Scope): NotesQuery {
+	if (scope === "agent" || scope === "model") return { scope };
+	return { scope };
+}
+
 /**
  * Acquire the five homes once for one boot. Only filesystem-style errno failures are isolated;
  * malformed note data and unrelated construction errors remain visible to the caller.
  */
-export function loadNotesSnapshot(ctx: ExtensionContext, loadHome: NotesLoader = (context, scope) => listNotes(context, { scope })): NotesSnapshot {
+export async function loadNotesSnapshot(ctx: ExtensionContext, loadHome?: NotesLoader, identity: NotesContext = notesContextFromPi(ctx)): Promise<NotesSnapshot> {
 	const openedAt = Date.now();
+	const store = createNotesStore(identity);
+	const load = loadHome ?? ((_context: ExtensionContext, scope: Scope) => store.list(queryForScope(scope)));
 	const homes = new Map<Scope, readonly NoteRow[]>();
 	const unavailable: NotesHome[] = [];
 	for (const home of NOTES_HOMES) {
 		try {
-			homes.set(home.scope, loadHome(ctx, home.scope));
+			homes.set(home.scope, await load(ctx, home.scope));
 		} catch (error) {
 			const code = typeof error === "object" && error !== null ? (error as NodeJS.ErrnoException).code : undefined;
 			if (typeof code !== "string" || !/^E[A-Z0-9_]+$/.test(code) || code.startsWith("ERR_")) throw error;

package/src/{notes → pi/notes}/tools.ts

@@ -1,11 +1,10 @@
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-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";
-import { type Origin } from "./frontmatter.js";
-import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+import { defineTool, generateDiffString, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { localIso } from "../../notes/frontmatter.js";
+import { createNotesStore, NoteError, type NoteChange, type NoteReadResult, type NoteRow, type NoteSearchRow, type Origin } from "../../notes/index.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 { notesContextFromPi } from "./adapter.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.",
@@ -15,23 +14,27 @@ const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session,
 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;
+		if (error.lineNumbers) payload.line_numbers = error.lineNumbers;
+		if (error.editIndex !== undefined) payload.edit_index = error.editIndex;
 		return output(payload);
 	}
 	throw error;
 }
 
+function renderDiff(change: NoteChange): string {
+	if (change.kind === "none") return "";
+	return generateDiffString(change.before, change.after).diff;
+}
+
 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.`,
+		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 createdAt 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);
-				writeNote(ctx, destination.path, content, { scope: destination.scope, who: destination.who, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				await createNotesStore(notesContextFromPi(ctx)).write(params.address, content, { origin: (params.origin ?? "self") as Origin, stale: params.stale });
 				return output({ address: params.address, written: true });
 			} catch (error) { return failure(error); }
 		},
@@ -43,8 +46,8 @@ export function registerNotesTools(pi: ExtensionAPI) {
 		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 { 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);
+				const { applied, change } = await createNotesStore(notesContextFromPi(ctx)).edit(params.address, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				const diff = renderDiff(change);
 				return output({ address: params.address, applied, diff });
 			} catch (error) { return failure(error); }
 		},
@@ -55,10 +58,9 @@ export function registerNotesTools(pi: ExtensionAPI) {
 		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 in the shared READ WINDOW block: concatenate only the content after the block to reconstruct the note.`,
 		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>;
+			let note: NoteReadResult | undefined;
 			try {
-				const destination = assertAddress(params.address);
-				note = readNote(ctx, destination.path, destination.scope, destination.who);
+				note = await createNotesStore(notesContextFromPi(ctx)).read(params.address);
 			} catch (error) { return failure(error); }
 			if (!note) return output({ error: "note not found", address: params.address });
 			const text = note.text;
@@ -76,9 +78,9 @@ export function registerNotesTools(pi: ExtensionAPI) {
 		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>;
-			try { rows = listNotes(ctx, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
-			const files: Array<{ address: string; stale: boolean; updated_at: string; address_truncated?: boolean }> = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updated_at) }));
+			let rows: NoteRow[];
+			try { rows = await createNotesStore(notesContextFromPi(ctx)).list({ pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
+			const files: Array<{ address: string; stale: boolean; updated_at: string; address_truncated?: boolean }> = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updatedAt) }));
 			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 }));
@@ -93,12 +95,12 @@ export function registerNotesTools(pi: ExtensionAPI) {
 		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); }
+			let rows: NoteSearchRow[];
+			try { rows = await createNotesStore(notesContextFromPi(ctx)).search(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; updated_at: string; stale: boolean; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; offset_chars: number }>; address_truncated?: boolean }> = rows.map((row) => {
 				const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, offset_chars: match.offsetChars }));
-				return { address: row.address, updated_at: localIso(row.meta.updated_at), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+				return { address: row.address, updated_at: localIso(row.meta.updatedAt), stale: row.meta.stale, 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;

package/src/protocol.ts

@@ -4,16 +4,12 @@ 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 MAX_NOTE_BYTES = 1_000_000;
+export { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./notes/constants.js";
 export const POCKET_SESSION_LIMIT = 5;
 export const POCKET_PROJECT_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.
-export const MAX_NOTE_PATH_BYTES = 512;
 export const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
 export const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
 export const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
@@ -57,4 +53,7 @@ Session notes belong to this trip — the goal, the progress, the loose ends. Th
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 
 export const WARNING_PROMPT =
-	"Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): 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. Do not continue any task. Then call wipe_memory IMMEDIATELY — anything not in the note dies with the window.";
+	"Your memory is about to be erased. Stop the current task and write the note NOW. If it already exists, revise it with notes_edit (or rewrite it whole): 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. Use as many note/tool turns as needed to finish the checkpoint. When it is ready, call wipe_memory to reset immediately; otherwise finish normally and the extension will reset at your normal stop. Anything not in the note dies with the window.";
+
+/** Identical hidden close-out message for manual and budget-triggered requests. */
+export const WARNING_CONTENT = `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;

package/src/text-match.ts

@@ -0,0 +1,13 @@
+/**
+ * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
+ * none occurs. Shared by the two search tools so a match address is computed identically.
+ */
+export function earliestMatchOffsetChars(text: string, queries: string[]): number {
+	let earliest = -1;
+	for (const query of queries) {
+		const index = text.indexOf(query);
+		if (index < 0) continue;
+		if (earliest < 0 || index < earliest) earliest = index;
+	}
+	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}

package/src/tool-output.ts

@@ -1,3 +1,5 @@
+export { earliestMatchOffsetChars } from "./text-match.js";
+
 export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
 export const DEFAULT_READ_WINDOW_CHARS = 12000;
 export const MAX_READ_WINDOW_CHARS = 50000;
@@ -125,20 +127,6 @@ export function readWindowBlock(identity: ReadonlyArray<readonly [string, string
 	return `--- READ WINDOW ---\n${fields}\nchars: [${window.offset_chars},${end}) of ${window.total_chars}\nnext_offset_chars: ${next}\n`;
 }
 
-/**
- * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
- * none occurs. Shared by the two search tools so a match address is computed identically.
- */
-export function earliestMatchOffsetChars(text: string, queries: string[]): number {
-	let earliest = -1;
-	for (const query of queries) {
-		const index = text.indexOf(query);
-		if (index < 0) continue;
-		if (earliest < 0 || index < earliest) earliest = index;
-	}
-	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
-}
-
 /** Shrink a single page item to fit; only invoked when that item alone exceeds the budget. */
 export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;