pi-posthorse 0.10.1 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.10.1",
+	"version": "0.10.3",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. No-summary context rollover for Pi, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": [
@@ -31,21 +31,24 @@
 		"image": "https://raw.githubusercontent.com/fitchmultz/pi-posthorse/main/diagram.png"
 	},
 	"scripts": {
-		"check": "tsc",
-		"quality:prepare": "node scripts/quality-prepare.ts",
-		"quality:policy": "node scripts/quality-policy.ts && node scripts/config-policy.ts",
-		"quality:probes": "npm run quality:prepare && node --test test/quality*.test.ts",
-		"lint": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings .",
-		"lint:agent": "npm run quality:prepare && npm run quality:policy && oxlint --deny-warnings --format=agent .",
-		"lint:fix": "npm run quality:prepare && npm run quality:policy && oxlint --fix .",
+		"check": "tsc --noEmit",
+		"quality:policy": "node scripts/quality-policy.ts",
+		"quality:probes": "node --test test/quality*.test.ts",
+		"lint": "node scripts/verify.ts quality:policy quality:config lint:oxlint",
+		"lint:agent": "node scripts/verify.ts quality:policy quality:config lint:agent:oxlint",
+		"lint:fix": "node scripts/verify.ts quality:policy quality:config lint:fix:oxlint",
 		"format": "oxfmt --write .",
 		"format:check": "oxfmt --check .",
 		"build": "npm pack --dry-run",
-		"verify": "node scripts/toolchain-policy.ts && npm run lint && npm run format:check && npm run check:compat && npm run build",
-		"check:compat": "npm run check && npm test",
+		"verify": "node scripts/toolchain-policy.ts && node scripts/verify.ts quality:policy quality:config lint:oxlint format:check check test build",
+		"check:compat": "node scripts/verify.ts check test",
 		"test:native": "node --import ./test/pi-loader.ts --test test/host.test.mjs",
-		"test": "npm run quality:prepare && node --import ./test/pi-loader.ts --test test/*.test.ts test/host.test.mjs",
-		"prepublishOnly": "npm run verify"
+		"test": "node --import ./test/pi-loader.ts --test test/*.test.ts test/host.test.mjs",
+		"prepublishOnly": "npm run verify",
+		"quality:config": "node scripts/config-policy.ts",
+		"lint:oxlint": "oxlint --deny-warnings .",
+		"lint:agent:oxlint": "oxlint --deny-warnings --format=agent .",
+		"lint:fix:oxlint": "oxlint --fix ."
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": ">=1.3.0",
@@ -68,10 +71,10 @@
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "24.19.1",
-		"oxc-parser": "0.153.0",
-		"oxfmt": "0.72.0",
-		"oxlint": "1.87.0",
-		"oxlint-tsgolint": "7.0.2003",
+		"oxc-parser": "0.156.0",
+		"oxfmt": "0.75.0",
+		"oxlint": "1.90.0",
+		"oxlint-tsgolint": "7.0.2005",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2",
 		"yaml": "2.9.1"

package/src/context-tools.ts

@@ -71,7 +71,7 @@ export function registerContextTools(
 			),
 		}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(id, { handoff }, _signal, _onUpdate, ctx) {
 			const trimmed = handoff?.trim();
 			const limit = freshPayloadChars(policy(ctx), activeToolTokens());
@@ -99,7 +99,7 @@ export function registerContextTools(
 			"verify remaining context before reporting a token count or changing plans because of context limits",
 		parameters: Type.Object({}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
 			return contextReport(policy(ctx));
 		},

package/src/contracts.ts

@@ -4,7 +4,7 @@ import type { PosthorseDisplay } from "../ui.ts";
 export type CompactionPolicy = {
 	readonly enabled: boolean;
 	readonly reserveTokens: number;
-	readonly keepRecentTokens?: number;
+	readonly keepRecentTokens?: number | undefined;
 };
 export type ContextUsage = {
 	readonly tokens: number | null;
@@ -17,49 +17,56 @@ export type PolicyContext = {
 	readonly getSystemPrompt: () => string;
 };
 export type PolicyReader = (ctx: ExtensionContext) => CompactionPolicy;
+export type SnapshotReader = (
+	ctx: ExtensionContext,
+	livePolicy?: CompactionPolicy,
+) => PolicyContext;
 export type ImageLike = {
 	readonly type: "image";
 	readonly data: string;
 	readonly mimeType: string;
 };
 export type ToolCallLike = {
-	readonly type?: string;
-	readonly id?: string;
-	readonly name?: string;
-	readonly namespace?: string;
+	readonly type?: string | undefined;
+	readonly id?: string | undefined;
+	readonly name?: string | undefined;
+	readonly namespace?: string | undefined;
 	readonly arguments?: unknown;
 	readonly executionArguments?: unknown;
-	readonly async?: boolean;
+	readonly async?: boolean | undefined;
 };
 export type MessageLike = {
-	readonly role?: string;
-	readonly stopReason?: string;
-	readonly errorMessage?: string;
+	readonly role?: string | undefined;
+	readonly stopReason?: string | undefined;
+	readonly errorMessage?: string | undefined;
 	readonly content?: unknown;
-	readonly summary?: string;
-	readonly toolName?: string;
-	readonly namespace?: string;
-	readonly toolCallId?: string;
-	readonly isError?: boolean;
-	readonly command?: string;
-	readonly output?: string;
-	readonly excludeFromContext?: boolean;
+	readonly summary?: string | undefined;
+	readonly toolName?: string | undefined;
+	readonly customType?: string | undefined;
+	readonly namespace?: string | undefined;
+	readonly toolCallId?: string | undefined;
+	readonly isError?: boolean | undefined;
+	readonly details?: unknown;
+	readonly nestedCalls?: unknown;
+	readonly command?: string | undefined;
+	readonly output?: string | undefined;
+	readonly excludeFromContext?: boolean | undefined;
 };
 export type EntryLike = {
-	readonly type?: string;
-	readonly id?: string;
-	readonly parentId?: string | null;
-	readonly timestamp?: string;
-	readonly message?: MessageLike;
-	readonly summary?: string;
-	readonly customType?: string;
+	readonly type?: string | undefined;
+	readonly id?: string | undefined;
+	readonly parentId?: string | null | undefined;
+	readonly timestamp?: string | undefined;
+	readonly message?: MessageLike | undefined;
+	readonly summary?: string | undefined;
+	readonly customType?: string | undefined;
 	readonly content?: unknown;
 	readonly details?: unknown;
-	readonly display?: boolean;
-	readonly handoff?: string;
-	readonly firstKeptEntryId?: string | null;
-	readonly targetId?: string;
-	readonly replacement?: { readonly content: unknown } | null;
+	readonly display?: boolean | undefined;
+	readonly handoff?: string | undefined;
+	readonly firstKeptEntryId?: string | null | undefined;
+	readonly targetId?: string | undefined;
+	readonly replacement?: { readonly content: unknown } | null | undefined;
 };
 export type WindowedEntry = {
 	readonly entry: EntryLike;
@@ -79,8 +86,8 @@ export type HistoryHit = {
 };
 export type ReminderFingerprint = {
 	readonly windowId: string;
-	readonly contextWindow?: number;
-	readonly reserveTokens?: number;
+	readonly contextWindow?: number | undefined;
+	readonly reserveTokens?: number | undefined;
 };
 export type TextResult = {
 	content: Array<

package/src/files.ts

@@ -45,22 +45,18 @@ export async function resolveFileTarget(absolutePath: string): Promise<string> {
 		if (target.endsWith(sep) || target.endsWith("/")) {
 			// Trailing separators require an existing directory, never a new regular file.
 			// Resolution follows dependent links in filesystem order.
-			// oxlint-disable-next-line no-await-in-loop
 			await stat(target);
 			return realpath(target);
 		}
 		const parentInput = dirname(target);
 		// stat enforces regular-file/.. traversal that macOS realpath alone accepts.
-		// oxlint-disable-next-line no-await-in-loop
 		if (!(await stat(parentInput)).isDirectory()) {
 			throw Object.assign(new Error(`Not a directory: ${parentInput}`), { code: "ENOTDIR" });
 		}
 		// Each parent must resolve before its child link can be examined.
-		// oxlint-disable-next-line no-await-in-loop
 		const parent = await realpath(parentInput);
 		target = join(parent, basename(target));
 		// Link targets cannot be known before examining the current link.
-		// oxlint-disable-next-line no-await-in-loop
 		const info = await lstatOrMissing(target);
 		if (info === undefined) {
 			return target;
@@ -73,7 +69,6 @@ export async function resolveFileTarget(absolutePath: string): Promise<string> {
 		}
 		links.add(target);
 		// Preserve .. until the preceding directory symlink has been followed.
-		// oxlint-disable-next-line no-await-in-loop
 		const link = await readlink(target);
 		target = isAbsolute(link) ? link : `${parent}${sep}${link}`;
 	}

package/src/guidance.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { buildGuidance } from "./budget.ts";
+import type { SnapshotReader } from "./contracts.ts";
+
+export function registerGuidance(pi: ExtensionAPI, policy: SnapshotReader): void {
+	let promptOptions: { readonly forceSystemPrompt?: string } | undefined;
+	pi.on("before_agent_start", (event) => {
+		promptOptions = event.systemPromptOptions;
+	});
+	pi.on("agent_settled", () => {
+		// Prompt options belong to one run, never to later idle context evaluation.
+		promptOptions = undefined;
+	});
+	pi.on("context_with_system", (event, ctx) => {
+		const guidance = buildGuidance(policy(ctx));
+		const system =
+			event.messages.findLast(
+				(message) =>
+					message.role === "system" && typeof message.sections?.posthorse === "string",
+			) ?? event.messages.find((message) => message.role === "system");
+		if (system === undefined || system.role !== "system") {
+			return;
+		}
+		if (promptOptions?.forceSystemPrompt !== undefined) {
+			// ponytail: Pi applies forced prompts after this hook; keep request-local guidance
+			// until the host projects forced text before context_with_system.
+			event.messages.splice(1, 0, {
+				role: "custom",
+				customType: "posthorse-guidance",
+				content: guidance,
+				display: false,
+				timestamp: 0,
+			});
+		} else {
+			system.sections = {
+				...system.sections,
+				posthorse: `<posthorse>\n${guidance}\n</posthorse>`,
+			};
+		}
+	});
+}

package/src/history-entries.ts

@@ -36,10 +36,10 @@ export function contextStart(entries: readonly EntryLike[]): {
 } {
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
-		if (entry.type === "context_window") {
+		if (entry?.type === "context_window") {
 			return { start: i + 1, boundary: entry };
 		}
-		if (entry.type === "compaction") {
+		if (entry?.type === "compaction") {
 			const kept = entries.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
 			return { start: kept >= 0 ? kept : i + 1, boundary: entry };
 		}
@@ -101,27 +101,26 @@ function contentText(content: unknown): string {
 		.join("\n");
 }
 function ownAssistantText(message: MessageLike, images: WindowedEntry["images"]): string[] {
-	const originals = [""];
+	const originals: string[] = [];
+	let current = "";
 	for (const part of unknownArray(message.content) ?? []) {
 		if (isRecoveryCall(part)) {
-			originals.push("");
+			originals.push(current);
+			current = "";
 		} else {
 			const partText = textOf({ content: [part] });
-			const index = originals.length - 1;
 			if (partText !== "") {
-				originals[index] += `${originals[index] === "" ? "" : "\n"}${partText}`;
+				current = current === "" ? partText : `${current}\n${partText}`;
 			}
 		}
 	}
-	const metadata = [assistantFailure(message), imageSummary(images)]
+	const last = [current, assistantFailure(message), imageSummary(images)]
 		.filter((part) => part !== "")
 		.join("\n");
-	const last = originals.length - 1;
-	if (metadata !== "") {
-		originals[last] += `${originals[last] === "" ? "" : "\n"}${metadata}`;
-	}
-	if (originals[0] !== "") {
-		originals[0] = `[assistant] ${originals[0]}`;
+	originals.push(last);
+	const first = originals[0] ?? "";
+	if (first !== "") {
+		originals[0] = `[assistant] ${first}`;
 	}
 	return originals;
 }
@@ -228,9 +227,10 @@ export function windowProjection(): (entry: EntryLike) => string {
 export function* reverseWindowEntries(entries: readonly EntryLike[]): Generator<WindowedEntry> {
 	// Preserve parent-relative window labels without normalizing the whole branch.
 	// ponytail: ancestry still scans metadata; a native window-aware iterator could remove that cost.
-	const windows = entries.map(windowProjection());
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const item = toWindowedEntry(entries[i], windows[i]);
+	const project = windowProjection();
+	const windows = entries.map((entry) => ({ entry, windowId: project(entry) }));
+	for (const { entry, windowId } of windows.reverse()) {
+		const item = toWindowedEntry(entry, windowId);
 		if (item !== undefined) {
 			yield item;
 		}

package/src/history-pages.ts

@@ -13,7 +13,7 @@ import type { PageAccess } from "./paging.ts";
 type SearchPage = {
 	readonly parts: readonly string[];
 	readonly spans: readonly { readonly headerLength: number; readonly length: number }[];
-	readonly next?: string;
+	readonly next?: string | undefined;
 };
 function cursorFor(matches: HistoryMatches, hit: HistoryHit, offset: number): string {
 	return Buffer.from(JSON.stringify([hit.id, hit.priority, offset, matches.key])).toString(

package/src/history-search.ts

@@ -30,7 +30,7 @@ export type HistoryParams = {
 export type HistorySource = {
 	readonly dir: string;
 	readonly cwd: string;
-	readonly currentFile?: string;
+	readonly currentFile?: string | undefined;
 	readonly branch: () => readonly EntryLike[];
 	readonly projection: () => readonly ProjectedEntry[];
 };
@@ -38,7 +38,7 @@ export type HistoryCursor = readonly [id: string, priority: 0 | 1, offset: numbe
 export type HistoryMatches = {
 	readonly hits: readonly HistoryHit[];
 	readonly skipped: number;
-	readonly cursor?: HistoryCursor;
+	readonly cursor?: HistoryCursor | undefined;
 	readonly key: string;
 	readonly limit: number;
 };
@@ -109,7 +109,7 @@ function contextVisibility(project: HistorySource["projection"]): (entry: EntryL
 	};
 }
 type SearchProgress = {
-	readonly cursor?: HistoryCursor;
+	readonly cursor?: HistoryCursor | undefined;
 	readonly limit: number;
 	readonly add: (hit: HistoryHit) => void;
 	readonly seeking: (priority: 0 | 1) => boolean;
@@ -201,8 +201,8 @@ async function scanArchive(
 	options: {
 		readonly source: string;
 		readonly query: string;
-		readonly signal?: AbortSignal;
-		readonly wanted?: LineMatcher;
+		readonly signal?: AbortSignal | undefined;
+		readonly wanted?: LineMatcher | undefined;
 		readonly inContext: (entry: EntryLike) => boolean;
 	},
 	accumulator: SearchProgress,
@@ -231,7 +231,7 @@ async function archivedMatches(
 	source: HistorySource,
 	search: {
 		readonly query: string;
-		readonly signal?: AbortSignal;
+		readonly signal?: AbortSignal | undefined;
 		readonly inContext: (entry: EntryLike) => boolean;
 	},
 	accumulator: SearchProgress,

package/src/history.ts

@@ -10,7 +10,10 @@ import type { PageAccess } from "./paging.ts";
 import { scopedSessionFiles, sessionWindowEntries } from "./session-files.ts";
 
 type LocatedEntry = { readonly item: WindowedEntry; readonly source: string };
-function entryReference(id: string): { readonly entryId: string; readonly fileKey?: string } {
+function entryReference(id: string): {
+	readonly entryId: string;
+	readonly fileKey?: string | undefined;
+} {
 	const separator = id.indexOf("@");
 	return {
 		entryId: separator < 0 ? id : id.slice(0, separator),
@@ -125,7 +128,7 @@ export function registerHistory(
 			),
 		}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const source = historySource(ctx);
 			if (params.op === "search") {

package/src/notes.ts

@@ -84,7 +84,6 @@ async function* folderEntries(directory: string, signal: AbortSignal | undefined
 			.slice(0, firstFolder === -1 ? batch.length : firstFolder + 1)
 			.map((entry) => join(directory, entry.name));
 		// Stats overlap only up to the next entry that may be a folder.
-		// oxlint-disable-next-line no-await-in-loop
 		const infos = await Promise.all(paths.map(statIfPresent));
 		for (const [index, path] of paths.entries()) {
 			start += 1;
@@ -148,7 +147,6 @@ async function listNotes(
 	const rows: string[] = [];
 	for (let start = 0; start < files.length; start += FORMAT_BATCH) {
 		// Pi gets an event-loop turn before each batch of rows.
-		// oxlint-disable-next-line no-await-in-loop
 		await setImmediate();
 		signal?.throwIfAborted();
 		for (const file of files.slice(start, start + FORMAT_BATCH)) {
@@ -274,7 +272,6 @@ async function noteHits(
 		// A batch of notes over 1 MiB reads nothing that would notice cancellation.
 		signal?.throwIfAborted();
 		// Batches keep note order, so a search stops within one batch of the page limit.
-		// oxlint-disable-next-line no-await-in-loop
 		const batch = await Promise.all(
 			notes
 				.slice(start, start + SEARCH_BATCH)
@@ -364,7 +361,7 @@ export function registerNotes(
 			),
 		}),
 		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
-		// oxlint-disable-next-line max-params
+		// oxlint-disable-next-line max-params -- QX-002: Pi supplies five fixed positional tool arguments.
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			const dir = notesDir(ctx.cwd);
 			const access: NotesAccess = { host: () => policy(ctx), pages, signal };

package/src/paging.ts

@@ -14,8 +14,8 @@ import {
 export type PageRequest = {
 	readonly offset: number;
 	readonly imageCount?: number;
-	readonly cursor?: string;
-	readonly imageOffset?: number;
+	readonly cursor?: string | undefined;
+	readonly imageOffset?: number | undefined;
 };
 export type NotesPage = {
 	readonly rows: readonly string[];