pi-posthorse 0.10.3 → 0.10.4

package/src/note-guards.ts

@@ -0,0 +1,203 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	addressOf,
+	canonicalPath,
+	inside,
+	notePath,
+	sameScope,
+	scopeDirectory,
+	type NoteAddress,
+	type NoteTouchRecord,
+} from "./note-scopes.ts";
+import { noteOperations, verifiedNoteOperations, type NoteOperation } from "./note-tool-effects.ts";
+import type { NoteCall, NotesStore, SessionNotes } from "./note-store.ts";
+
+/** Native core tools expand @/~ paths; pi-apply-edits deliberately treats them literally. */
+function toolPath(tool: string, path: string, cwd: string): string {
+	if (tool !== "read" && tool !== "write" && tool !== "edit") {
+		if (process.platform === "win32") {
+			return resolve(cwd, path);
+		}
+		return isAbsolute(path) ? path : `${cwd}/${path}`;
+	}
+	let normalized = path
+		.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/gu, " ")
+		.replace(/^@/u, "");
+	if (normalized === "~" || normalized.startsWith("~/")) {
+		normalized = join(homedir(), normalized.slice(1));
+	}
+	if (normalized.startsWith("file://")) {
+		normalized = fileURLToPath(normalized);
+	}
+	return resolve(cwd, normalized);
+}
+type CapturedCall = {
+	readonly session: SessionNotes;
+	readonly call: NoteCall;
+	readonly cwd: string;
+	readonly tool: string;
+};
+async function noteAddress(path: string, session: SessionNotes): Promise<NoteAddress | undefined> {
+	const known = addressOf(path, session.scopes);
+	if (known !== undefined) {
+		return known;
+	}
+	for (const { root } of session.scopes) {
+		const parts = relative(root, canonicalPath(path)).split(sep);
+		if (
+			parts[0] !== ".forks" ||
+			parts[1] === undefined ||
+			parts[2] !== "notes" ||
+			parts.length < 4
+		) {
+			continue;
+		}
+		const scope = await session.selectScope(join(root, ".forks", parts[1], "notes"));
+		return addressOf(path, [scope]);
+	}
+	return;
+}
+function existingEdit(tool: string, operation: NoteOperation): boolean {
+	return (
+		operation.action === "edit" ||
+		operation.action === "delete" ||
+		(tool === "write_files" && (operation.action === "write" || operation.action === "clear"))
+	);
+}
+async function guardForeign(
+	address: NoteAddress,
+	operation: NoteOperation,
+	captured: CapturedCall,
+): Promise<string> {
+	const { session, tool, call } = captured;
+	if (operation.action === "read") {
+		return `This is another notes scope. Use notes read with ${JSON.stringify({ scope: scopeDirectory(address), path: address.path })} for a labeled read-only comparison, or omit scope to read this session’s copy.`;
+	}
+	return existingEdit(tool, operation) &&
+		session.scopes.some((scope) => sameScope(scope, address))
+		? session.guardReference(address.path, call)
+		: `The foreign note was not changed. This session writes ${notePath(session.binding, address.path)}. Retry explicitly there; creation semantics were not changed.`;
+}
+async function guardOperation(
+	operation: NoteOperation,
+	captured: CapturedCall,
+): Promise<string | undefined> {
+	const { session, call, tool, cwd } = captured;
+	const path = toolPath(tool, operation.path, cwd);
+	const address = await noteAddress(path, session);
+	if (address === undefined) {
+		return operation.action !== "read" &&
+			session.scopes.some((scope) =>
+				inside(canonicalPath(join(scope.root, ".forks")), canonicalPath(path)),
+			)
+			? `Managed notes metadata is not editable through file tools: ${path}. Use notes for this session’s checkpoint.`
+			: undefined;
+	}
+	if (!sameScope(address, session.binding)) {
+		return guardForeign(address, operation, captured);
+	}
+	if (existingEdit(tool, operation) && !session.owns(address.path)) {
+		const copied = await withFileMutationQueue(path, () => session.adopt(address.path, call));
+		if (copied) {
+			return `Private copy created at ${path}; no requested edit ran. Read this copy, then retry the edit.`;
+		}
+	}
+	if (operation.action !== "read") {
+		await session.prepareWrite();
+	}
+	return;
+}
+async function recordedFiles(
+	operations: readonly NoteOperation[],
+	captured: CapturedCall,
+): Promise<NoteTouchRecord["files"]> {
+	const files: NoteTouchRecord["files"][number][] = [];
+	for (const operation of operations) {
+		// Each result belongs to the scope captured before execution, even after /tree.
+		const address = await noteAddress(
+			toolPath(captured.tool, operation.path, captured.cwd),
+			captured.session,
+		);
+		if (address === undefined) {
+			continue;
+		}
+		let kind: NoteTouchRecord["files"][number]["kind"] = "write";
+		switch (operation.action) {
+			case "read":
+			case "delete":
+				kind = operation.action;
+				break;
+			case "clear":
+			case "create-empty":
+				kind = "clear";
+				break;
+			case "append":
+			case "create":
+			case "edit":
+			case "write":
+				break;
+		}
+		files.push({ ...address, kind });
+	}
+	return files;
+}
+export function registerNoteGuards(pi: ExtensionAPI, store: NotesStore): void {
+	const calls = new Map<string, CapturedCall>();
+	pi.on("tool_call", async (event, ctx) => {
+		const operations = noteOperations(event.toolName, event.input);
+		const session = await store.get(ctx).catch((error: unknown) => {
+			if (
+				event.toolName === "notes" ||
+				operations.some((operation) =>
+					store
+						.roots()
+						.some((root) =>
+							inside(
+								root,
+								canonicalPath(toolPath(event.toolName, operation.path, ctx.cwd)),
+							),
+						),
+				)
+			) {
+				throw error;
+			}
+			return;
+		});
+		if (session === undefined) {
+			return;
+		}
+		const call = session.startCall(event.toolCallId, event.parentToolCallId);
+		const captured = { session, call, cwd: ctx.cwd, tool: event.toolName };
+		calls.set(event.toolCallId, captured);
+		if (event.toolName === "notes" || operations.length === 0) {
+			return;
+		}
+		for (const operation of operations) {
+			// Preflight never mutates arguments; a copied reference needs a fresh read before retry.
+			const reason = await guardOperation(operation, captured);
+			if (reason !== undefined) {
+				return { block: true, reason };
+			}
+		}
+		return;
+	});
+	pi.on("tool_result", async (event) => {
+		const captured = calls.get(event.toolCallId);
+		if (captured === undefined || event.toolName === "notes") {
+			return;
+		}
+		const details: unknown = event.details;
+		const operations = verifiedNoteOperations(event.toolName, event.input, {
+			details,
+			isError: event.isError,
+		});
+		captured.session.record(await recordedFiles(operations, captured), captured.call);
+	});
+	pi.on("tool_execution_end", (event) => {
+		calls.get(event.toolCallId)?.session.finishCall(event.toolCallId);
+		calls.delete(event.toolCallId);
+	});
+}

package/src/note-inventory.ts

@@ -0,0 +1,111 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { isRecord } from "./contracts.ts";
+import {
+	canonicalPath,
+	inside,
+	notePath,
+	scopeDirectory,
+	type NoteIdentity,
+	type NoteScope,
+} from "./note-scopes.ts";
+import { fileIdentity } from "./note-snapshots.ts";
+
+export type NoteFile = NoteIdentity & { readonly path: string };
+/** Maximum overlapped stats; 16, 64 and 256 were equivalent on the measured 212,751-note tree. */
+const WALK_BATCH = 64;
+async function statIfPresent(path: string) {
+	try {
+		return await stat(path);
+	} catch (error) {
+		if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+			return;
+		}
+		throw error;
+	}
+}
+/** Preserve depth-first listing order and recheck later entries after visiting each folder. */
+async function* folderEntries(directory: string, signal: AbortSignal | undefined) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	let start = 0;
+	while (start < entries.length) {
+		signal?.throwIfAborted();
+		const batch = entries.slice(start, start + WALK_BATCH);
+		const firstFolder = batch.findIndex(
+			(entry) => entry.isDirectory() || entry.isSymbolicLink(),
+		);
+		const paths = batch
+			.slice(0, firstFolder === -1 ? batch.length : firstFolder + 1)
+			.map((entry) => join(directory, entry.name));
+		const infos = await Promise.all(paths.map(statIfPresent));
+		for (const [index, path] of paths.entries()) {
+			start += 1;
+			const info = infos[index];
+			if (info !== undefined) {
+				yield { path, info, alias: batch[index]?.isSymbolicLink() === true };
+			}
+			if (info?.isDirectory() === true) {
+				break;
+			}
+		}
+	}
+}
+type WalkState = {
+	readonly ancestors: readonly string[];
+	readonly scope: NoteScope;
+	readonly notice: (text: string) => void;
+};
+function allowedTarget(path: string, state: WalkState): boolean {
+	const scopeRoot = canonicalPath(scopeDirectory(state.scope));
+	if (state.scope.scope === "") {
+		return !inside(canonicalPath(join(state.scope.root, ".forks")), path);
+	}
+	if (inside(scopeRoot, path)) {
+		return true;
+	}
+	state.notice(`Not indexed: alias outside private notes scope (${path}).`);
+	return false;
+}
+async function walk(
+	directory: string,
+	signal: AbortSignal | undefined,
+	state: WalkState,
+): Promise<NoteFile[]> {
+	signal?.throwIfAborted();
+	const root = await realpath(directory);
+	if (state.ancestors.includes(root) || !allowedTarget(root, state)) {
+		return [];
+	}
+	const next: WalkState = { ...state, ancestors: [...state.ancestors, root] };
+	const files: NoteFile[] = [];
+	for await (const { path, info, alias } of folderEntries(directory, signal)) {
+		if (info.isDirectory()) {
+			for (const file of await walk(path, signal, next)) {
+				files.push(file);
+			}
+		} else if (!alias || allowedTarget(canonicalPath(path), state)) {
+			files.push({ path, ...fileIdentity(info) });
+		}
+	}
+	return files;
+}
+export async function notesUnder(
+	scope: NoteScope,
+	folder: string | undefined,
+	options: { readonly signal: AbortSignal | undefined; readonly notice: (text: string) => void },
+): Promise<NoteFile[]> {
+	const target =
+		folder === undefined || folder === "" || folder === "."
+			? scopeDirectory(scope)
+			: notePath(scope, folder);
+	const info = await statIfPresent(target);
+	options.signal?.throwIfAborted();
+	if (info === undefined) {
+		return [];
+	}
+	const files = info.isDirectory()
+		? await walk(target, options.signal, { scope, ancestors: [], notice: options.notice })
+		: [{ path: target, ...fileIdentity(info) }];
+	options.signal?.throwIfAborted();
+	return files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}

package/src/note-provenance.ts

@@ -0,0 +1,299 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord, type EntryLike } from "./contracts.ts";
+import { sessionLines } from "./session-lines.ts";
+import { parseSessionLine } from "./session-files.ts";
+import { sessionNoteTouches } from "./note-evidence.ts";
+import { readManifest, snapshot, type SnapshotNote } from "./note-snapshots.ts";
+import {
+	addressOf,
+	bindingsOf,
+	canonicalPath,
+	forkScope,
+	notePath,
+	sameOwner,
+	sameScope,
+	scopeDirectory,
+	ownedPaths,
+	seedsOf,
+	type ForkBinding,
+	type NoteAddress,
+	type NoteBinding,
+	type NoteScope,
+} from "./note-scopes.ts";
+
+type NotesManager = ExtensionContext["sessionManager"];
+export type NoteSource = {
+	readonly entries: readonly EntryLike[];
+	readonly file: string | undefined;
+};
+type Candidate = SnapshotNote & { readonly cleared: boolean };
+function includedJournalType(type: string | undefined, legacy: boolean): boolean {
+	return legacy || type === undefined || type === "session" || type === "custom";
+}
+async function journalMetadata(
+	file: string,
+	legacy: boolean,
+	signal?: AbortSignal,
+): Promise<readonly EntryLike[]> {
+	const entries: EntryLike[] = [];
+	try {
+		for await (const line of sessionLines(file, signal)) {
+			const type = /^\s*\{\s*"type"\s*:\s*"([^"]+)"/u.exec(line.head)?.[1];
+			if (!includedJournalType(type, legacy)) {
+				continue;
+			}
+			const entry = parseSessionLine(await line.text());
+			if (entry !== undefined && includedJournalType(entry.type, legacy)) {
+				entries.push(entry);
+			}
+		}
+	} catch (error) {
+		if (!isRecord(error) || error.code !== "ENOENT") {
+			throw error;
+		}
+	}
+	return entries;
+}
+/** Read only; opening a SessionManager here could migrate or create an archived source. */
+export async function sourceEntries(
+	file: string | undefined,
+	signal?: AbortSignal,
+): Promise<readonly EntryLike[]> {
+	let current = file;
+	const seen = new Set<string>();
+	const entries: EntryLike[] = [];
+	while (current !== undefined && !seen.has(current)) {
+		seen.add(current);
+		// Each ancestor's current ownership prevents falling through a deleted owned file.
+		const metadata = await journalMetadata(current, false, signal);
+		entries.push(...metadata);
+		current = metadata.find((entry) => entry.type === "session")?.parentSession;
+	}
+	return entries;
+}
+function legacySource(entries: readonly EntryLike[]): NoteScope | undefined {
+	const { touches, defaultDir } = sessionNoteTouches({
+		branch: entries,
+		allEntries: entries,
+		projected: [],
+		retained: new Set(),
+	});
+	const roots = new Set(defaultDir === undefined ? [] : [defaultDir]);
+	for (const touch of touches) {
+		if (touch.absPath !== undefined && touch.absPath.endsWith(`/${touch.notePath}`)) {
+			roots.add(touch.absPath.slice(0, -touch.notePath.length - 1));
+		}
+	}
+	if ([...roots].some((root) => !isAbsolute(root))) {
+		return;
+	}
+	const canonical = new Set([...roots].map(canonicalPath));
+	const [root] = canonical;
+	return canonical.size === 1 && root !== undefined ? { root, scope: "" } : undefined;
+}
+async function sourceScope(
+	manager: NotesManager,
+	source: NoteSource,
+): Promise<NoteScope | undefined> {
+	const header = source.entries.find((entry) => entry.type === "session");
+	const bindings = bindingsOf([...manager.getEntries(), ...source.entries]);
+	const binding =
+		header?.id === undefined || header.timestamp === undefined
+			? bindings.at(-1)
+			: bindings.findLast(
+					(candidate) =>
+						candidate.owner.id === header.id &&
+						candidate.owner.timestamp === header.timestamp,
+				);
+	if (binding !== undefined) {
+		return binding;
+	}
+	const legacy =
+		source.file === undefined ? manager.getEntries() : await journalMetadata(source.file, true);
+	return legacySource(legacy.length > 0 ? legacy : manager.getEntries());
+}
+export async function resolveReference(
+	scope: NoteScope,
+	path: string,
+	entries: readonly EntryLike[],
+): Promise<NoteAddress | undefined> {
+	let source: NoteScope | null = scope;
+	const bindings = bindingsOf(entries);
+	const visited = new Set<string>();
+	while (source !== null) {
+		const current: NoteScope = source;
+		const directory = scopeDirectory(current);
+		if (visited.has(directory)) {
+			throw new Error(`Cyclic note provenance at ${directory}.`);
+		}
+		visited.add(directory);
+		if (existsSync(notePath(current, path))) {
+			return { ...current, path };
+		}
+		// A manifest includes later adoptions; the journal includes later writes and deletions.
+		const binding: NoteBinding | undefined =
+			(await readManifest(directory)) ??
+			bindings.findLast((candidate) => sameScope(candidate, current));
+		if (
+			binding === undefined ||
+			binding.kind === "project" ||
+			ownedPaths(binding, entries).has(path)
+		) {
+			return;
+		}
+		source = binding.source;
+	}
+	return;
+}
+function touchedCandidates(
+	evidence: ReturnType<typeof sessionNoteTouches>,
+	scopes: readonly NoteScope[],
+	allEntries: readonly EntryLike[],
+): Map<string, Candidate> {
+	const bindings = bindingsOf(allEntries);
+	const selected = new Map<string, Candidate>();
+	for (const touch of evidence.touches) {
+		const absolute =
+			touch.absPath ??
+			(evidence.defaultDir === undefined
+				? undefined
+				: join(evidence.defaultDir, touch.notePath));
+		const address = absolute === undefined ? undefined : addressOf(absolute, scopes);
+		if (address === undefined) {
+			continue;
+		}
+		const owner = bindings.findLast((binding) => sameScope(binding, address));
+		const lineage =
+			owner === undefined
+				? address
+				: (seedsOf(owner, allEntries).find((seed) => seed.path === address.path)?.lineage ??
+					address);
+		selected.set(address.path, {
+			path: address.path,
+			source: address,
+			lineage,
+			anchors: [touch.receiptId ?? touch.entryId],
+			cleared: touch.kind === "clear",
+		});
+	}
+	return selected;
+}
+function seedCandidates(
+	manager: NotesManager,
+	source: NoteSource,
+	scope: NoteScope | undefined,
+): Candidate[] {
+	const allEntries = [...manager.getEntries(), ...source.entries];
+	const bindings = bindingsOf(allEntries);
+	const scopes = scope === undefined ? bindings : [...bindings, scope];
+	const evidence = sessionNoteTouches({
+		branch: manager.getBranch(),
+		allEntries,
+		projected: manager.buildSessionProjection().entries,
+		retained: new Set(),
+		directories: new Set(scopes.map(scopeDirectory)),
+	});
+	if (scope === undefined && evidence.touches.length > 0) {
+		throw new Error(
+			"Incomplete notes snapshot: the source notes root is missing or ambiguous.",
+		);
+	}
+	const selected = touchedCandidates(evidence, scopes, allEntries);
+	for (const binding of bindings) {
+		for (const seed of seedsOf(binding, allEntries)) {
+			if (
+				!selected.has(seed.path) &&
+				seed.anchors.some((id) => evidence.visibleIds.has(id))
+			) {
+				selected.set(seed.path, {
+					...seed,
+					source: { root: binding.root, scope: binding.scope, path: seed.path },
+					cleared: false,
+				});
+			}
+		}
+	}
+	return [...selected.values()];
+}
+async function forkBinding(
+	manager: NotesManager,
+	binding: ForkBinding,
+	source: NoteSource,
+): Promise<ForkBinding> {
+	const scope = await sourceScope(manager, source);
+	const candidates = seedCandidates(manager, source, scope);
+	const entries = [...manager.getEntries(), ...source.entries];
+	const files: SnapshotNote[] = [];
+	const absent: string[] = [];
+	for (const candidate of candidates) {
+		// Resolve against the immediate parent's files, not a historical ancestor's version.
+		const address = await resolveReference(scope ?? candidate.source, candidate.path, entries);
+		if (address !== undefined) {
+			files.push({
+				path: candidate.path,
+				source: address,
+				lineage: candidate.lineage,
+				anchors: candidate.anchors,
+			});
+		} else if (candidate.cleared) {
+			absent.push(candidate.path);
+		} else {
+			throw new Error(
+				`Incomplete notes snapshot: source note ${candidate.path} is unavailable.`,
+			);
+		}
+	}
+	return snapshot(
+		{
+			...binding,
+			source: scope === undefined ? null : { root: scope.root, scope: scope.scope },
+			absent,
+		},
+		files,
+	);
+}
+export async function loadNotesBinding(
+	manager: NotesManager,
+	root: string,
+): Promise<{
+	readonly binding: NoteBinding;
+	readonly source: NoteSource;
+	readonly created: boolean;
+}> {
+	const header = manager.getHeader();
+	if (header === null) {
+		throw new Error("Pi did not supply the session header for notes ownership.");
+	}
+	const owner = { id: header.id, timestamp: header.timestamp };
+	const own = bindingsOf(manager.getEntries()).findLast((binding) =>
+		sameOwner(binding.owner, owner),
+	);
+	const source: NoteSource = {
+		entries: await sourceEntries(header.parentSession),
+		file: header.parentSession,
+	};
+	if (own !== undefined) {
+		return { binding: own, source, created: false };
+	}
+	const inherited = bindingsOf([...manager.getEntries(), ...source.entries]);
+	const fork = header.parentSession !== undefined || inherited.length > 0;
+	const binding: NoteBinding = fork
+		? await forkBinding(
+				manager,
+				{
+					version: 1,
+					kind: "fork",
+					owner,
+					root,
+					scope: forkScope(owner),
+					source: null,
+					seeds: [],
+					absent: [],
+				},
+				source,
+			)
+		: { version: 1, kind: "project", owner, root, scope: "" };
+	return { binding, source, created: true };
+}