pi-posthorse 0.10.2 → 0.10.4

package/src/note-discovery.ts

@@ -0,0 +1,291 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { isRecord } from "./contracts.ts";
+import { sessionNoteTouches } from "./note-evidence.ts";
+import { notesUnder, type NoteFile } from "./note-inventory.ts";
+import { fileDigest, fileIdentity, readManifest, sameIdentity } from "./note-snapshots.ts";
+import {
+	sameScope,
+	scopeDirectory,
+	type ForkBinding,
+	type NoteAddress,
+	type NoteIdentity,
+	type NoteScope,
+	type NoteSeed,
+} from "./note-scopes.ts";
+import type { SessionNotes } from "./note-store.ts";
+
+export type DiscoveredNote = NoteFile & {
+	readonly address: NoteAddress;
+	readonly lineage: NoteAddress;
+	readonly seed: NoteSeed | undefined;
+	readonly copies: readonly NoteAddress[];
+};
+type ScopeInventory = { readonly scope: NoteScope; readonly manifest: ForkBinding | undefined };
+type DiscoveryOptions = {
+	readonly path?: string | undefined;
+	readonly scope?: string | undefined;
+	readonly signal: AbortSignal | undefined;
+};
+type ComparisonOptions = DiscoveryOptions & { readonly notice: (message: string) => void };
+type DigestCache = {
+	readonly identity: NoteIdentity;
+	readonly digest: string;
+	readonly revision: number;
+};
+async function projectScopes(
+	session: SessionNotes,
+	notice: (message: string) => void,
+): Promise<ScopeInventory[]> {
+	const scopes: ScopeInventory[] = [
+		{ scope: { root: session.binding.root, scope: "" }, manifest: undefined },
+	];
+	const directory = join(session.binding.root, ".forks");
+	const entries = await readdir(directory, { withFileTypes: true }).catch((error: unknown) => {
+		if (isRecord(error) && error.code === "ENOENT") {
+			return [];
+		}
+		throw error;
+	});
+	for (const entry of entries) {
+		const path = join(directory, entry.name);
+		if (entry.name.startsWith(".staging-")) {
+			continue;
+		}
+		const manifest = entry.isDirectory() ? await readManifest(join(path, "notes")) : undefined;
+		if (manifest === undefined || manifest.root !== session.binding.root) {
+			notice(`Not indexed: unmanaged or incomplete notes data at ${path}.`);
+		} else {
+			scopes.push({ scope: manifest, manifest });
+		}
+	}
+	if (!scopes.some(({ scope }) => sameScope(scope, session.binding))) {
+		scopes.push({
+			scope: session.binding,
+			manifest: session.binding.kind === "fork" ? session.binding : undefined,
+		});
+	}
+	return scopes;
+}
+async function scopedFiles(
+	inventory: ScopeInventory,
+	options: DiscoveryOptions,
+	notice: (message: string) => void,
+): Promise<DiscoveredNote[]> {
+	const files = await notesUnder(inventory.scope, options.path, {
+		signal: options.signal,
+		notice,
+	});
+	const seeds = new Map(inventory.manifest?.seeds.map((seed) => [seed.path, seed]));
+	return files.map((file) => {
+		const path = relative(scopeDirectory(inventory.scope), file.path);
+		const address = { root: inventory.scope.root, scope: inventory.scope.scope, path };
+		const seed = seeds.get(path);
+		return Object.assign({}, file, {
+			address,
+			seed,
+			lineage: seed?.lineage ?? address,
+			copies: [],
+		});
+	});
+}
+function noteKey(address: NoteAddress): string {
+	return JSON.stringify([address.root, address.scope, address.path]);
+}
+export function noteReadTarget(note: DiscoveredNote): string {
+	return JSON.stringify({ scope: scopeDirectory(note.address), path: note.address.path });
+}
+export function noteLabel(note: DiscoveredNote, session: SessionNotes, labeled: boolean): string {
+	if (!labeled) {
+		return note.address.path;
+	}
+	const mode = sameScope(note.address, session.binding) ? "current" : "read-only";
+	const copies =
+		note.copies.length === 0
+			? ""
+			: `; identical copies: ${note.copies.map((copy) => JSON.stringify({ scope: scopeDirectory(copy), path: copy.path })).join(", ")}`;
+	return `${note.address.path} [${mode}; read ${noteReadTarget(note)}${copies}]`;
+}
+async function readReference(
+	session: SessionNotes,
+	path: string,
+	signal: AbortSignal | undefined,
+): Promise<DiscoveredNote | undefined> {
+	const target = await session.read(path, { signal });
+	if (target.writable) {
+		return;
+	}
+	const info = await stat(target.path).catch((error: unknown) => {
+		if (isRecord(error) && error.code === "ENOENT") {
+			return;
+		}
+		throw error;
+	});
+	if (info?.isFile() !== true) {
+		return;
+	}
+	return {
+		...fileIdentity(info),
+		path: target.path,
+		address: target.address,
+		lineage: target.address,
+		seed: undefined,
+		copies: [],
+	};
+}
+export class NoteDiscovery {
+	readonly #digests = new Map<string, DigestCache>();
+	#knownDigest(note: DiscoveredNote, revision: number): string | undefined {
+		const cached = this.#digests.get(note.path);
+		if (
+			cached !== undefined &&
+			cached.revision === revision &&
+			sameIdentity(cached.identity, note)
+		) {
+			return cached.digest;
+		}
+		if (revision === 0 && note.seed !== undefined && sameIdentity(note.seed.identity, note)) {
+			return note.seed.digest;
+		}
+		return;
+	}
+	async #digest(
+		note: DiscoveredNote,
+		session: SessionNotes,
+		options: ComparisonOptions,
+	): Promise<string | undefined> {
+		const { signal } = options;
+		const revision = session.revision(note.path);
+		const known = this.#knownDigest(note, revision);
+		if (known !== undefined) {
+			return known;
+		}
+		try {
+			const digest = await fileDigest(note.path, signal);
+			if (!sameIdentity(note, await stat(note.path))) {
+				return;
+			}
+			this.#digests.set(note.path, { identity: note, digest, revision });
+			return digest;
+		} catch (error) {
+			signal?.throwIfAborted();
+			options.notice(
+				`Duplicate comparison unavailable for ${noteReadTarget(note)}: ${error instanceof Error ? error.message : String(error)}. Copies remain separate.`,
+			);
+			return;
+		}
+	}
+	async #collapse(
+		files: readonly DiscoveredNote[],
+		session: SessionNotes,
+		options: ComparisonOptions,
+	): Promise<DiscoveredNote[]> {
+		const groups = new Map<string, DiscoveredNote[]>();
+		for (const file of files) {
+			const key = `${noteKey(file.lineage)}\0${file.size}`;
+			const group = groups.get(key) ?? [];
+			group.push(file);
+			groups.set(key, group);
+		}
+		const selected: DiscoveredNote[] = [];
+		for (const group of groups.values()) {
+			if (group.length === 1) {
+				selected.push(...group);
+				continue;
+			}
+			const matches = new Map<string, DiscoveredNote>();
+			group.sort(
+				(a, b) =>
+					Number(sameScope(b.address, session.binding)) -
+					Number(sameScope(a.address, session.binding)),
+			);
+			for (const file of group) {
+				// Only same-lineage, same-size candidates need content comparison.
+				const digest = await this.#digest(file, session, options);
+				const previous = digest === undefined ? undefined : matches.get(digest);
+				if (previous === undefined || digest === undefined) {
+					matches.set(digest ?? noteKey(file.address), file);
+				} else {
+					matches.set(digest, {
+						...previous,
+						copies: [...previous.copies, file.address],
+					});
+				}
+			}
+			selected.push(...matches.values());
+		}
+		return selected;
+	}
+	async #references(session: SessionNotes, options: DiscoveryOptions): Promise<DiscoveredNote[]> {
+		if (session.binding.kind !== "fork" || options.scope !== undefined) {
+			return [];
+		}
+		const recovery = session.recovery;
+		const { touches } = sessionNoteTouches({
+			branch: session.branch,
+			allEntries: recovery.entries,
+			projected: session.projection,
+			retained: new Set(),
+			directories: new Set(session.scopes.map(scopeDirectory)),
+		});
+		const paths = new Set(touches.map((touch) => touch.notePath));
+		const files: DiscoveredNote[] = [];
+		for (const path of paths) {
+			if (
+				session.owns(path) ||
+				(options.path !== undefined &&
+					path !== options.path &&
+					!path.startsWith(`${options.path}/`))
+			) {
+				continue;
+			}
+			const file = await readReference(session, path, options.signal);
+			if (file !== undefined) {
+				files.push(file);
+			}
+		}
+		return files;
+	}
+	async list(
+		session: SessionNotes,
+		options: DiscoveryOptions,
+	): Promise<{
+		readonly files: readonly DiscoveredNote[];
+		readonly notices: readonly string[];
+		readonly labeled: boolean;
+	}> {
+		const notices: string[] = [];
+		const notice = (text: string) => {
+			notices.push(text);
+		};
+		const scopes =
+			options.scope === undefined
+				? await projectScopes(session, notice)
+				: [
+						{
+							scope: await session.selectScope(options.scope),
+							manifest: await readManifest(options.scope),
+						},
+					];
+		const files: DiscoveredNote[] = [];
+		for (const scope of scopes) {
+			// Preserve native listing order while walking each scope independently.
+			files.push(...(await scopedFiles(scope, options, notice)));
+		}
+		for (const reference of await this.#references(session, options)) {
+			if (!files.some((file) => noteKey(file.address) === noteKey(reference.address))) {
+				files.push(reference);
+			}
+		}
+		const selected =
+			options.scope === undefined
+				? await this.#collapse(files, session, { ...options, notice })
+				: files;
+		return {
+			files: selected.sort((a, b) => b.mtimeMs - a.mtimeMs),
+			notices,
+			labeled:
+				scopes.length > 1 || scopes.some(({ scope }) => !sameScope(scope, session.binding)),
+		};
+	}
+}

package/src/note-evidence.ts

@@ -0,0 +1,179 @@
+import { join } from "node:path";
+import { isRecord, optionalString, type EntryLike, type ProjectedEntry } from "./contracts.ts";
+import { contextEdits } from "./history-entries.ts";
+import { collectTouches, type NoteTouch, type ScannedNoteEntry } from "./recovery-note-touches.ts";
+import {
+	addressOf,
+	bindingsOf,
+	notePath,
+	ownedPaths,
+	sameOwner,
+	sameScope,
+	scopeDirectory,
+	touchRecords,
+	type NoteBinding,
+} from "./note-scopes.ts";
+
+export type NotesRecovery = {
+	readonly binding: NoteBinding;
+	readonly entries: readonly EntryLike[];
+};
+
+export type NoteEvidence = {
+	readonly branch: readonly EntryLike[];
+	readonly allEntries: readonly EntryLike[];
+	readonly projected: readonly ProjectedEntry[];
+	readonly retained: ReadonlySet<string>;
+	readonly directories?: ReadonlySet<string>;
+};
+/** Compaction removes context, not provenance. Only active-branch edits suppress old receipts. */
+function projectedNotes(evidence: NoteEvidence): ScannedNoteEntry[] {
+	const edits = contextEdits(evidence.branch);
+	const omitted = new Set(
+		evidence.projected
+			.filter(({ messages }) => messages.length === 0)
+			.map(({ sourceEntry }) => sourceEntry.id),
+	);
+	return evidence.branch.flatMap((entry) => {
+		const id = entry.id ?? "";
+		const edit = edits.get(id);
+		if (omitted.has(id) || edit?.replacement === null) {
+			return [];
+		}
+		const effective =
+			edit?.replacement !== undefined && entry.type === "message"
+				? { ...entry, message: { ...entry.message, content: edit.replacement.content } }
+				: entry;
+		return [
+			{ entry: effective, entryId: edit?.id ?? id, inRetained: evidence.retained.has(id) },
+		];
+	});
+}
+function receiptKey(entry: EntryLike): string | undefined {
+	if (entry.type === "message" && entry.message?.role === "toolResult") {
+		return entry.message.toolCallId;
+	}
+	return entry.type === "custom_message" && isRecord(entry.details)
+		? optionalString(entry.details.runId)
+		: undefined;
+}
+function effectReceipts(branch: readonly EntryLike[]): ReadonlyMap<string, EntryLike> {
+	const receipts = new Map<string, EntryLike>();
+	for (const entry of branch) {
+		const key = receiptKey(entry);
+		if (key !== undefined) {
+			// A delivered completion wins over the launch, including when an edit omits it.
+			receipts.set(key, entry);
+		}
+	}
+	return receipts;
+}
+function recordedTouches(
+	evidence: NoteEvidence,
+	visible: readonly ScannedNoteEntry[],
+): NoteTouch[] {
+	const receipts = effectReceipts(evidence.branch);
+	const shown = new Map(visible.map((item) => [item.entry.id, item]));
+	const seen = new Set<string>();
+	return touchRecords(evidence.allEntries).flatMap((record) => {
+		const receipt = receipts.get(record.rootToolCallId);
+		const item = shown.get(receipt?.id);
+		const key = `${record.owner.id}\0${record.owner.timestamp}\0${record.toolCallId}`;
+		if (item === undefined || seen.has(key)) {
+			return [];
+		}
+		seen.add(key);
+		return record.files.map((file): NoteTouch => {
+			let kind: NoteTouch["kind"] = "observed-write";
+			if (file.kind === "read") {
+				kind = "read";
+			} else if (file.kind === "delete" || file.kind === "clear") {
+				kind = "clear";
+			}
+			return {
+				notePath: file.path,
+				absPath: join(scopeDirectory(file), file.path),
+				kind,
+				entryId: item.entryId,
+				receiptId: item.entry.id ?? item.entryId,
+				inRetained: false,
+				owner: record.owner,
+			};
+		});
+	});
+}
+function touchKey(touch: NoteTouch): string {
+	return JSON.stringify([touch.receiptId ?? touch.entryId, touch.absPath ?? touch.notePath]);
+}
+export function sessionNoteTouches(evidence: NoteEvidence): {
+	readonly touches: readonly NoteTouch[];
+	readonly defaultDir: string | undefined;
+	readonly visibleIds: ReadonlySet<string>;
+} {
+	const visible = projectedNotes(evidence);
+	const directories = new Set([
+		...bindingsOf(evidence.allEntries).map(scopeDirectory),
+		...(evidence.directories ?? []),
+	]);
+	const legacy = collectTouches(visible, directories);
+	const recorded = recordedTouches(evidence, visible);
+	const recordedByReceipt = new Map(recorded.map((touch) => [touchKey(touch), touch]));
+	const covered = new Set<string>();
+	const identified = legacy.touches.map((touch) => {
+		const key = touchKey(touch);
+		covered.add(key);
+		return { ...touch, owner: recordedByReceipt.get(key)?.owner };
+	});
+	const touches = [...identified, ...recorded.filter((touch) => !covered.has(touchKey(touch)))];
+	const order = new Map(visible.map((entry, index) => [entry.entry.id ?? entry.entryId, index]));
+	touches.sort(
+		(a, b) =>
+			(order.get(a.receiptId ?? a.entryId) ?? 0) - (order.get(b.receiptId ?? b.entryId) ?? 0),
+	);
+	return {
+		touches,
+		defaultDir: legacy.defaultDir,
+		visibleIds: new Set(visible.map((item) => item.entry.id ?? "")),
+	};
+}
+
+/** Inherited history describes source bytes, not necessarily the bytes snapshotted at fork time. */
+export function scopeRecoveryTouches(
+	touches: readonly NoteTouch[],
+	recovery: NotesRecovery | undefined,
+): readonly NoteTouch[] {
+	if (recovery === undefined || recovery.binding.kind === "project") {
+		return touches;
+	}
+	const owned = ownedPaths(recovery.binding, recovery.entries);
+	const scopes = [
+		recovery.binding,
+		...bindingsOf(recovery.entries),
+		...(recovery.binding.source === null ? [] : [recovery.binding.source]),
+	];
+	return touches.map((touch): NoteTouch => {
+		const address = touch.absPath === undefined ? undefined : addressOf(touch.absPath, scopes);
+		if (address !== undefined && sameScope(address, recovery.binding)) {
+			return touch;
+		}
+		const currentOwner =
+			touch.owner !== undefined && sameOwner(touch.owner, recovery.binding.owner);
+		if (owned.has(touch.notePath) && !currentOwner) {
+			return {
+				...touch,
+				absPath: notePath(recovery.binding, touch.notePath),
+				kind:
+					touch.kind === "read" || touch.kind === "clear" ? touch.kind : "observed-write",
+				inRetained: false,
+			};
+		}
+		return address === undefined
+			? touch
+			: {
+					...touch,
+					kind: "read",
+					referenceScope: scopeDirectory(address),
+					inRetained: false,
+				};
+	});
+}

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);
+	});
+}