@astrosheep/pi-context 0.22.1 → 0.23.1

package/src/notes/tools.ts

@@ -1,10 +1,10 @@
 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 { 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 { serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { 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")], {
@@ -12,10 +12,6 @@ const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("sel
 }));
 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.";
 
-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 };
@@ -35,28 +31,28 @@ export function registerNotesTools(pi: ExtensionAPI) {
 			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) });
+				writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				return output({ address: params.address, written: true });
 			} 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.`,
+		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 the address 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) });
+				const { applied, 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, diff });
 			} 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.`,
+		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>;
@@ -65,27 +61,24 @@ export function registerNotesTools(pi: ExtensionAPI) {
 				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 text = note.text;
 			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 });
+				return outputRaw(readWindowBlock([["address", params.address]], window), content, { address: params.address, ...rest });
 			}, (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.`,
+		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.`,
 		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) }));
+			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) }));
 			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 }));
@@ -96,16 +89,16 @@ 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 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).`,
+		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.`,
 		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 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) };
 			});
 			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
 				if (fits(file)) return file;

package/src/reset-lifecycle.ts

@@ -12,7 +12,16 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 	isCurrentReset: (entryId: string, ctx: ExtensionContext) => boolean;
 	onReset: (entryId: string) => void;
 }) {
-	type Attempt = { completed: boolean; sessionId: string; explicit: boolean };
+	type Attempt = {
+		completed: boolean;
+		explicit: boolean;
+		nextRequested: boolean;
+		continuationStarted: boolean;
+		sessionId: string;
+		settled: boolean;
+		wait: Promise<void>;
+		release: () => void;
+	};
 	type Request =
 		| { phase: "idle" }
 		| { phase: "requested" }
@@ -21,38 +30,39 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 	let handledEntry: string | undefined;
 	let active = true;
 
+	const release = (attempt: Attempt) => {
+		if (attempt.settled) return;
+		attempt.settled = true;
+		if (state.phase === "compacting" && state.attempt === attempt) {
+			state = { phase: "idle" };
+			handledEntry = undefined;
+		}
+		attempt.release();
+	};
 	const clear = () => {
+		if (state.phase === "compacting") release(state.attempt);
 		state = { phase: "idle" };
 		handledEntry = undefined;
 	};
 	const valid = (request: Attempt, ctx: ExtensionContext) =>
 		active && options.isEnabled() && state.phase === "compacting" && state.attempt === request && ctx.sessionManager.getSessionId() === request.sessionId;
 
-	// State is intentionally not resumed from a pending request: a loaded session must
-	// not execute work from a tool that belonged to a previous runtime or tree branch.
-	pi.on("session_start", () => { clear(); active = true; });
-	pi.on("session_shutdown", () => { clear(); active = false; });
-	pi.on("session_tree", clear);
-
-	pi.on("agent_end", (_event, ctx) => {
-		if (!active || !options.isEnabled()) return;
-		if (ctx.signal?.aborted) {
-			// Esc cancels the user's run. Do not reset or resurrect it at settled.
-			state = { phase: "idle" };
-			return;
-		}
-	});
-
-	pi.on("agent_settled", (_event, ctx) => {
-		if (!active || !options.isEnabled() || state.phase === "compacting" || !ctx.isIdle()) return;
-		if (state.phase !== "requested") return;
-		// One owner for requested resets. Consume the request before any external call;
-		// repeated settled events and reentrant callbacks are harmless.
-		const request: Attempt = { completed: false, sessionId: ctx.sessionManager.getSessionId(), explicit: true };
+	const begin = (ctx: ExtensionContext) => {
+		let releaseWait!: () => void;
+		const request: Attempt = {
+			completed: false,
+			explicit: true,
+			nextRequested: false,
+			continuationStarted: false,
+			sessionId: ctx.sessionManager.getSessionId(),
+			settled: false,
+			wait: new Promise<void>((resolve) => { releaseWait = resolve; }),
+			release: () => releaseWait(),
+		};
 		state = { phase: "compacting", attempt: request };
 		const onError = (error: Error) => {
 			if (!valid(request, ctx)) return;
-			state = { phase: "idle" };
+			release(request);
 			// Do not retry from settled in a tight loop. A later prompt may trigger a
 			// native reset or explicitly request one.
 			ctx.ui.notify(`pi-context: reset did not complete (${error.message}). The conversation is retained; resume with another prompt.`, "warning");
@@ -61,19 +71,64 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 			ctx.compact({
 				onComplete: () => {
 					if (!valid(request, ctx)) return;
-					state = { phase: "idle" };
 					// session_compact only confirms the boundary. onComplete runs after
 					// Pi clears compaction state; sending inside the hook starts too early.
 					// A queued user prompt may already have started at compaction_end.
 					if (request.completed && ctx.isIdle() && !ctx.hasPendingMessages()) {
-						pi.sendMessage(options.continuation, { triggerTurn: true });
+						// The SDK detaches sendMessage, so own the next settled event before
+						// starting it. The originating agent_settled handler awaits wait.
+						if (request.continuationStarted) return;
+						request.continuationStarted = true;
+						try {
+							pi.sendMessage(options.continuation, { triggerTurn: true });
+						} catch (error) {
+							onError(error instanceof Error ? error : new Error(String(error)));
+						}
+						return;
 					}
+					release(request);
 				},
 				onError,
 			});
 		} catch (error) {
 			onError(error instanceof Error ? error : new Error(String(error)));
 		}
+		return request;
+	};
+
+	// State is intentionally not resumed from a pending request: a loaded session must
+	// not execute work from a tool that belonged to a previous runtime or tree branch.
+	pi.on("session_start", () => { clear(); active = true; });
+	pi.on("session_shutdown", () => { clear(); active = false; });
+	pi.on("session_tree", clear);
+
+	pi.on("agent_end", (_event, ctx) => {
+		if (!active || !options.isEnabled()) return;
+		if (ctx.signal?.aborted) {
+			// Esc cancels the user's run. Do not reset or resurrect it at settled.
+			clear();
+		}
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (!active || !options.isEnabled() || !ctx.isIdle()) return;
+		if (state.phase === "compacting" && state.attempt.continuationStarted) {
+			const preceding = state.attempt;
+			if (!preceding.nextRequested) {
+				release(preceding);
+				return;
+			}
+			// This settled event belongs to the continuation started by preceding.
+			// If it requested another reset, retain preceding until that reset's own
+			// continuation settles. Its eventual nested handler only releases its own
+			// waiter, so it never awaits itself.
+			const next = begin(ctx);
+			return next.wait.then(() => release(preceding));
+		}
+		if (state.phase !== "requested") return;
+		// One owner for requested resets. Consume the request before any external call;
+		// repeated settled events and reentrant callbacks are harmless.
+		return begin(ctx).wait;
 	});
 
 	pi.on("session_before_compact", (event, ctx) => {
@@ -103,9 +158,15 @@ export function registerResetLifecycle(pi: ExtensionAPI, options: {
 
 	return {
 		request() {
-			const pending = state.phase !== "idle";
-			if (!pending) state = { phase: "requested" };
-			return pending ? "rollover_already_pending" : "rollover_requested";
+			if (state.phase === "idle") {
+				state = { phase: "requested" };
+				return "rollover_requested";
+			}
+			if (state.phase === "compacting" && state.attempt.continuationStarted && !state.attempt.nextRequested) {
+				state.attempt.nextRequested = true;
+				return "rollover_requested";
+			}
+			return "rollover_already_pending";
 		},
 		clear,
 	};

package/src/tool-output.ts

@@ -115,16 +115,14 @@ export function readCharacterWindow<T>(text: string, offsetChars: number | undef
 }
 
 /**
- * One-line bracketed header preceding a raw character-window payload: the identity, the
- * delivered char range, and either the resume cursor or `end`. `tail` appends extra
- * metadata (notes add their timestamps) inside the same brackets.
+ * Fixed metadata block preceding any raw character-window payload. Callers supply their
+ * source identity fields in wire order; range and continuation semantics are shared.
  */
-export function characterWindowHeader(identity: string, window: CharacterWindow, tail = ""): string {
-	// The range end is offset + delivered count, never `total_chars`: a read resolved past the
-	// end delivers zero characters there, and the header must not render an inverted range.
+export function readWindowBlock(identity: ReadonlyArray<readonly [string, string]>, window: CharacterWindow): string {
 	const end = window.offset_chars + Array.from(window.content).length;
-	const resume = window.next_offset_chars === null ? "end" : `continue at offset_chars=${window.next_offset_chars}`;
-	return `[${identity} · chars ${window.offset_chars}-${end} of ${window.total_chars} · ${resume}${tail}]`;
+	const next = window.next_offset_chars === null ? "null" : String(window.next_offset_chars);
+	const fields = identity.map(([name, value]) => `${name}: ${value}`).join("\n");
+	return `--- READ WINDOW ---\n${fields}\nchars: [${window.offset_chars},${end}) of ${window.total_chars}\nnext_offset_chars: ${next}\n`;
 }
 
 /**
@@ -183,9 +181,8 @@ export function output(value: unknown, details?: unknown, terminate = false) {
 }
 
 /**
- * Encode a prose payload as raw text: a one-line bracketed metadata header, then the payload
- * verbatim. The model reads the note or history item itself instead of a JSON envelope;
- * `details` carries the slim metadata object and never duplicates the payload.
+ * Encode a prose payload as raw text: metadata prefix, a blank line, then the payload
+ * verbatim. `details` carries the slim metadata object and never duplicates the payload.
  */
 export function outputRaw(header: string, content: string, details: unknown, terminate = false) {
 	return { content: [{ type: "text" as const, text: `${header}\n${content}` }], details, terminate };