pi-posthorse 0.8.0 → 0.8.2

package/src/history-search.ts

@@ -0,0 +1,308 @@
+import { relative, resolve } from "node:path";
+import {
+	isReminderType,
+	requireValue,
+	unknownArray,
+	type EntryLike,
+	type HistoryHit,
+	type ProjectedEntry,
+} from "./contracts.ts";
+import { historyHit, seenText, reverseWindowEntries } from "./history-entries.ts";
+import { shortKey } from "./message-text.ts";
+import {
+	filesContaining,
+	prefilterNeedles,
+	scopedSessionFiles,
+	sessionWindowEntries,
+} from "./session-files.ts";
+
+export type HistoryParams = {
+	readonly op: "search" | "read";
+	readonly query?: string;
+	readonly id?: string;
+	readonly all?: boolean;
+	readonly limit?: number;
+	readonly cursor?: string;
+	readonly offset?: number;
+	readonly imageOffset?: number;
+};
+export type HistorySource = {
+	readonly dir: string;
+	readonly cwd: string;
+	readonly currentFile?: string;
+	readonly branch: () => readonly EntryLike[];
+	readonly projection: () => readonly ProjectedEntry[];
+};
+export type HistoryCursor = readonly [id: string, priority: 0 | 1, offset: number, key: string];
+export type HistoryMatches = {
+	readonly hits: readonly HistoryHit[];
+	readonly skipped: number;
+	readonly cursor?: HistoryCursor;
+	readonly key: string;
+	readonly limit: number;
+};
+function cursorOffset(value: unknown, storedKey: unknown, key: string): number {
+	if (
+		typeof value !== "number" ||
+		!Number.isSafeInteger(value) ||
+		value < 0 ||
+		storedKey !== key
+	) {
+		throw new Error("Invalid cursor offset or scope.");
+	}
+	return value;
+}
+function decodeCursor(encoded: string | undefined, key: string): HistoryCursor | undefined {
+	if (encoded === undefined || encoded === "") {
+		return undefined;
+	}
+	const value: unknown = JSON.parse(Buffer.from(encoded, "base64url").toString());
+	const parts = unknownArray(value);
+	if (parts === undefined || parts.length !== 4) {
+		throw new Error("Invalid cursor tuple.");
+	}
+	const [id, priority, offset, storedKey] = parts;
+	if (typeof id !== "string" || id === "" || (priority !== 0 && priority !== 1)) {
+		throw new Error("Invalid cursor anchor.");
+	}
+	return [id, priority, cursorOffset(offset, storedKey, key), key];
+}
+function entryMessage(entry: EntryLike) {
+	switch (entry.type) {
+		case "message":
+			return entry.message ?? {};
+		case "context_edit":
+			return { content: entry.replacement?.content };
+		case "context_window":
+			return { content: entry.handoff };
+		case undefined:
+			return { content: entry.content, summary: entry.summary };
+		default:
+			return { content: entry.content, summary: entry.summary };
+	}
+}
+function contextVisibility(projected: readonly ProjectedEntry[]): (entry: EntryLike) => boolean {
+	const visible = new Map(
+		projected.flatMap(({ sourceEntry, messages }) =>
+			sourceEntry.id !== undefined && sourceEntry.id !== "" && messages.length > 0
+				? [[sourceEntry.id, messages.map(seenText).join("\n")]]
+				: [],
+		),
+	);
+	return (entry) => {
+		if (entry.type === "custom_message" && isReminderType(entry.customType)) {
+			return false;
+		}
+		const own = entryMessage(entry);
+		const id = entry.type === "context_edit" ? entry.targetId : entry.id;
+		return visible.get(id ?? "")?.includes(seenText(own)) === true;
+	};
+}
+type SearchProgress = {
+	readonly cursor?: HistoryCursor;
+	readonly limit: number;
+	readonly add: (hit: HistoryHit) => void;
+	readonly seeking: (priority: 0 | 1) => boolean;
+	readonly enough: () => boolean;
+};
+/** Owns ranking, lookahead and one cursor's progress; never holds the whole archive. */
+class SearchAccumulator {
+	readonly groups: [HistoryHit[], HistoryHit[]] = [[], []];
+	readonly cursor: HistoryCursor | undefined;
+	readonly limit: number;
+	private found: boolean;
+	private readonly fail: (message: string) => never;
+	constructor(
+		limit: number,
+		cursor: HistoryCursor | undefined,
+		fail: (message: string) => never,
+	) {
+		this.limit = limit;
+		this.cursor = cursor;
+		this.found = cursor === undefined;
+		this.fail = fail;
+	}
+	add(hit: HistoryHit): void {
+		const cursor = this.cursor;
+		if (cursor !== undefined && hit.priority < cursor[1]) {
+			return;
+		}
+		if (cursor !== undefined && hit.priority === cursor[1] && !this.found) {
+			if (hit.id !== cursor[0]) {
+				return;
+			}
+			this.found = true;
+			if (cursor[2] > hit.text.length) {
+				this.fail("History cursor is past the entry; restart the search without it.");
+			}
+			if (cursor[2] === hit.text.length) {
+				return;
+			}
+		}
+		if (this.groups[hit.priority].length <= this.limit) {
+			this.groups[hit.priority].push(hit);
+		}
+	}
+	seeking(priority: 0 | 1): boolean {
+		return this.cursor !== undefined && !this.found && priority === this.cursor[1];
+	}
+	enough(): boolean {
+		return this.groups[0].length > this.limit;
+	}
+	results(): HistoryHit[] {
+		if (!this.found) {
+			this.fail("History cursor entry no longer matches; restart the search without it.");
+		}
+		return this.groups.flat();
+	}
+}
+function archiveCollector(accumulator: SearchProgress): {
+	readonly add: (hit: HistoryHit) => void;
+	readonly finish: () => readonly (readonly HistoryHit[])[];
+} {
+	const recent: [HistoryHit[], HistoryHit[]] = [[], []];
+	let anchorHere = false;
+	return {
+		add: (hit) => {
+			const seeking = accumulator.seeking(hit.priority);
+			if (seeking && anchorHere) {
+				return;
+			}
+			if (seeking && hit.id === accumulator.cursor?.[0]) {
+				anchorHere = true;
+			}
+			const group = recent[hit.priority];
+			group.push(hit);
+			if (group.length > accumulator.limit + 2) {
+				group.shift();
+			}
+		},
+		finish: () => {
+			const cursor = accumulator.cursor;
+			if (cursor !== undefined && accumulator.seeking(cursor[1]) && !anchorHere) {
+				recent[cursor[1]] = [];
+			}
+			return recent;
+		},
+	};
+}
+async function scanArchive(
+	file: string,
+	options: {
+		readonly source: string;
+		readonly query: string;
+		readonly signal?: AbortSignal;
+		readonly inContext: (entry: EntryLike) => boolean;
+	},
+	accumulator: SearchProgress,
+): Promise<{ readonly groups: readonly (readonly HistoryHit[])[]; readonly skipped: number }> {
+	const collector = archiveCollector(accumulator);
+	let skipped = 0;
+	for await (const item of sessionWindowEntries(file, options.signal)) {
+		const hit = historyHit(item, options.query, options.source);
+		if (hit === undefined) {
+			continue;
+		}
+		if (options.inContext(item.entry)) {
+			skipped++;
+		} else {
+			collector.add(hit);
+		}
+	}
+	return { groups: collector.finish(), skipped };
+}
+async function archivedMatches(
+	source: HistorySource,
+	search: {
+		readonly query: string;
+		readonly signal?: AbortSignal;
+		readonly inContext: (entry: EntryLike) => boolean;
+	},
+	accumulator: SearchProgress,
+): Promise<number> {
+	const needles = prefilterNeedles(search.query);
+	const candidates =
+		needles === undefined
+			? undefined
+			: await filesContaining(source.dir, needles, search.signal);
+	const current =
+		source.currentFile === undefined || source.currentFile === ""
+			? undefined
+			: resolve(source.currentFile);
+	let skipped = 0;
+	for await (const file of scopedSessionFiles({
+		dir: source.dir,
+		cwd: source.cwd,
+		currentFile: source.currentFile,
+		signal: search.signal,
+		candidates: candidates === undefined ? undefined : (candidate) => candidates.has(candidate),
+	})) {
+		const inCurrent = resolve(file) === current;
+		const recent = await scanArchive(
+			file,
+			{
+				source: relative(source.dir, file),
+				query: search.query,
+				signal: search.signal,
+				inContext: (entry) => inCurrent && search.inContext(entry),
+			},
+			accumulator,
+		);
+		skipped += recent.skipped;
+		for (const group of recent.groups) {
+			for (const hit of [...group].reverse()) {
+				accumulator.add(hit);
+			}
+		}
+		if (accumulator.enough()) {
+			break;
+		}
+	}
+	return skipped;
+}
+function branchMatches(
+	source: HistorySource,
+	query: string,
+	inContext: (entry: EntryLike) => boolean,
+	accumulator: SearchProgress,
+): number {
+	let skipped = 0;
+	for (const item of reverseWindowEntries(source.branch())) {
+		const hit = historyHit(item, query);
+		if (hit === undefined) {
+			continue;
+		}
+		if (inContext(item.entry)) {
+			skipped++;
+			continue;
+		}
+		accumulator.add(hit);
+		if (accumulator.enough()) {
+			break;
+		}
+	}
+	return skipped;
+}
+export async function historyMatches(
+	source: HistorySource,
+	params: HistoryParams,
+	signal: AbortSignal | undefined,
+	fail: (message: string) => never,
+): Promise<HistoryMatches> {
+	const query = requireValue(params.query, "query", params.op).toLowerCase();
+	const limit = params.limit ?? 10;
+	const key = shortKey(JSON.stringify([query, params.all === true]));
+	let cursor: HistoryCursor | undefined;
+	try {
+		cursor = decodeCursor(params.cursor, key);
+	} catch {
+		fail("Invalid history cursor or changed query/scope; restart the search without it.");
+	}
+	const accumulator = new SearchAccumulator(limit, cursor, fail);
+	const inContext = contextVisibility(source.projection());
+	const skipped =
+		params.all === true
+			? await archivedMatches(source, { query, signal, inContext }, accumulator)
+			: branchMatches(source, query, inContext, accumulator);
+	return { hits: accumulator.results(), skipped, cursor, key, limit };
+}

package/src/history.ts

@@ -0,0 +1,146 @@
+import { relative, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolCards } from "../ui.ts";
+import { requireValue, type PolicyContext, type WindowedEntry } from "./contracts.ts";
+import { toWindowedEntry, windowProjection } from "./history-entries.ts";
+import { historyReadPage, searchPage } from "./history-pages.ts";
+import { historyMatches, type HistorySource } from "./history-search.ts";
+import type { PageAccess } from "./paging.ts";
+import { filesContaining, scopedSessionFiles, sessionWindowEntries } from "./session-files.ts";
+
+type LocatedEntry = { readonly item: WindowedEntry; readonly source: string };
+function entryReference(id: string): { readonly entryId: string; readonly fileKey?: string } {
+	const separator = id.indexOf("@");
+	return {
+		entryId: separator < 0 ? id : id.slice(0, separator),
+		fileKey: separator < 0 ? undefined : id.slice(separator + 1),
+	};
+}
+function branchEntry(source: HistorySource, id: string): WindowedEntry | undefined {
+	const project = windowProjection();
+	for (const entry of source.branch()) {
+		const windowId = project(entry);
+		const item = entry.id === id ? toWindowedEntry(entry, windowId) : undefined;
+		if (item !== undefined) {
+			return item;
+		}
+	}
+	return undefined;
+}
+async function findEntry(
+	source: HistorySource,
+	id: string,
+	signal?: AbortSignal,
+): Promise<LocatedEntry> {
+	const { entryId, fileKey } = entryReference(id);
+	const current = fileKey === undefined ? branchEntry(source, entryId) : undefined;
+	if (current !== undefined) {
+		return { item: current, source: "" };
+	}
+	const candidates =
+		fileKey === undefined && /^[\w-]+$/.test(entryId)
+			? await filesContaining(source.dir, [`"id":"${entryId}"`], signal)
+			: undefined;
+	for await (const file of scopedSessionFiles({
+		dir: source.dir,
+		cwd: source.cwd,
+		currentFile: source.currentFile,
+		signal,
+		fileKey,
+		candidates: candidates === undefined ? undefined : (candidate) => candidates.has(candidate),
+	})) {
+		for await (const item of sessionWindowEntries(file, signal, entryId)) {
+			return { item, source: relative(source.dir, file) };
+		}
+	}
+	throw new Error(
+		`No history entry "${id}" in this session or this project's other sessions. Pass an id exactly as history search prints it, such as 1a2f07de, or 1a2f07de@Ab3dE5fG7h from another session; search first when you only have text or a timestamp.`,
+	);
+}
+function historySource(ctx: ExtensionContext): HistorySource {
+	const manager = ctx.sessionManager;
+	return {
+		dir: manager.getSessionDir(),
+		cwd: resolve(ctx.cwd),
+		currentFile: manager.getSessionFile(),
+		branch: () => manager.getBranch(),
+		projection: () => manager.buildSessionProjection().entries,
+	};
+}
+export function registerHistory(
+	pi: ExtensionAPI,
+	policy: (ctx: ExtensionContext) => PolicyContext,
+	pages: PageAccess,
+): void {
+	pi.registerTool({
+		name: "history",
+		label: "History",
+		...toolCards("history"),
+		description:
+			"Search or read earlier session entries, including previous context windows. search skips entries still in your active context and lists original content before recovery echoes, newest first; all=true also searches this project's other sessions and subagent runs. read takes an entry id exactly as search printed it and pages text and images.",
+		promptSnippet: "recover earlier conversation that left the active context window",
+		promptGuidelines: [
+			"Use history search first, then history read with the entry id exactly as printed",
+		],
+		parameters: Type.Object({
+			op: Type.Union([Type.Literal("search"), Type.Literal("read")], {
+				description: "Operation to perform",
+			}),
+			query: Type.Optional(
+				Type.String({ description: "Case-insensitive text to find (search)" }),
+			),
+			id: Type.Optional(
+				Type.String({ description: "Entry id exactly as search printed it (read)" }),
+			),
+			all: Type.Optional(
+				Type.Boolean({
+					description: "Also search this project's other sessions and subagent runs",
+				}),
+			),
+			limit: Type.Optional(
+				Type.Integer({
+					description: "Maximum search results per page (default 10, max 50)",
+					minimum: 1,
+					maximum: 50,
+				}),
+			),
+			cursor: Type.Optional(
+				Type.String({
+					description:
+						"Continuation from the previous search page; keep query and all unchanged",
+					maxLength: 512,
+				}),
+			),
+			offset: Type.Optional(
+				Type.Integer({ description: "Character offset for read (default 0)", minimum: 0 }),
+			),
+			imageOffset: Type.Optional(
+				Type.Integer({
+					description:
+						"First image to return (read); use the value from the continuation",
+					minimum: 0,
+				}),
+			),
+		}),
+		// Pi's fixed tool contract supplies id, params, signal, updates, and context.
+		// oxlint-disable-next-line max-params
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const source = historySource(ctx);
+			if (params.op === "search") {
+				const fail = (message: string): never =>
+					pages.error(policy(ctx), message, params.cursor);
+				const matches = await historyMatches(source, params, signal, fail);
+				return searchPage(matches, params, policy(ctx), pages);
+			}
+			const id = requireValue(params.id, "id", params.op);
+			const located = await findEntry(source, id, signal);
+			return historyReadPage(
+				located.item,
+				params,
+				{ host: policy(ctx), pages },
+				located.source,
+			);
+		},
+	});
+}

package/src/message-text.ts

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { sep } from "node:path";
+import {
+	isRecord,
+	optionalString,
+	unknownArray,
+	type ImageLike,
+	type MessageLike,
+	type ToolCallLike,
+} from "./contracts.ts";
+
+export function isImage(part: unknown): part is ImageLike {
+	return (
+		isRecord(part) &&
+		part.type === "image" &&
+		typeof part.data === "string" &&
+		typeof part.mimeType === "string"
+	);
+}
+export function imagesOf(content: unknown): ImageLike[] {
+	return unknownArray(content)?.filter(isImage) ?? [];
+}
+export function imageSummary(images: readonly ImageLike[]): string {
+	if (images.length === 0) {
+		return "";
+	}
+	const types = [
+		...new Set(
+			images.map((image) => (image.mimeType === "" ? "unknown type" : image.mimeType)),
+		),
+	].join(", ");
+	return `[${images.length} image${images.length === 1 ? "" : "s"}: ${types}]`;
+}
+export function safeJsonStringify(value: unknown): string {
+	try {
+		const encoded: unknown = JSON.stringify(value);
+		return typeof encoded === "string" ? encoded : "undefined";
+	} catch {
+		return "[unserializable]";
+	}
+}
+export function toolIdentity(name?: string, namespace?: string): string {
+	return `${name ?? "tool"}${namespace === undefined ? "" : ` (namespace: ${safeJsonStringify(namespace)})`}`;
+}
+export function executionArgumentsText(call: ToolCallLike): string {
+	return call.executionArguments === undefined
+		? ""
+		: `\nExecution arguments: ${safeJsonStringify(call.executionArguments)}`;
+}
+export function toolCallOf(part: unknown): ToolCallLike | undefined {
+	if (!isRecord(part) || part.type !== "toolCall") {
+		return undefined;
+	}
+	return {
+		type: "toolCall",
+		id: optionalString(part.id),
+		name: optionalString(part.name),
+		namespace: optionalString(part.namespace),
+		arguments: part.arguments,
+		executionArguments: part.executionArguments,
+		async: part.async === true,
+	};
+}
+export function toolCalls(content: unknown): ToolCallLike[] {
+	return (unknownArray(content) ?? []).flatMap((part) => {
+		const call = toolCallOf(part);
+		return call === undefined ? [] : [call];
+	});
+}
+function blockText(part: unknown): string {
+	if (!isRecord(part)) {
+		return "";
+	}
+	if (part.type === "text") {
+		return optionalString(part.text) ?? "";
+	}
+	if (part.type === "thinking") {
+		return optionalString(part.thinking) ?? "";
+	}
+	const call = toolCallOf(part);
+	if (call === undefined) {
+		return "";
+	}
+	return `${toolIdentity(call.name, call.namespace)} ${safeJsonStringify(call.arguments ?? {})}${call.id === undefined ? "" : `\nCall ID: ${call.id}`}${executionArgumentsText(call)}`;
+}
+export function textOf(message: MessageLike): string {
+	if (typeof message.content === "string") {
+		return message.content;
+	}
+	return (unknownArray(message.content) ?? [])
+		.map(blockText)
+		.filter((text) => text !== "")
+		.join("\n");
+}
+export function assistantFailure(message: MessageLike): string {
+	if (message.role !== "assistant") {
+		return "";
+	}
+	const error = message.errorMessage ?? "";
+	if (message.stopReason !== "error" && message.stopReason !== "aborted" && error === "") {
+		return "";
+	}
+	return `[${message.stopReason ?? "error"}]${error === "" ? "" : ` ${error}`}`;
+}
+export function isRecoveryTool(name: unknown): boolean {
+	return name === "history" || name === "notes" || name === "new_context";
+}
+export function isRecoveryCall(part: unknown): boolean {
+	const block = toolCallOf(part);
+	return block !== undefined && isRecoveryTool(block.name);
+}
+/** Ten base64url characters of SHA-256; legacy whole-digest keys start with these. */
+export function shortKey(text: string): string {
+	return createHash("sha256").update(text).digest("base64url").slice(0, 10);
+}
+/** Nested session files are subagent runs, whose input came from a parent agent. */
+export function sourceTag(source: string): string {
+	return source.includes(sep) ? " [subagent]" : "";
+}
+export function excerptAround(text: string, index: number, before: number, length: number): string {
+	const start = Math.max(0, index - before);
+	const end = Math.min(text.length, start + length);
+	return `${start > 0 ? "…" : ""}${text.slice(start, end)}${end < text.length ? "…" : ""}`;
+}
+export function excerpt(text: string, limit: number): string {
+	if (text.length <= limit) {
+		return text;
+	}
+	const marker = "\n… middle omitted …\n";
+	if (limit <= marker.length) {
+		return text.slice(0, limit);
+	}
+	const head = Math.floor((limit - marker.length) / 2);
+	return `${text.slice(0, head)}${marker}${text.slice(text.length - (limit - marker.length - head))}`;
+}
+export function boundedBlock(header: string, text: string, limit: number): string {
+	const textLimit = Math.max(0, limit - header.length - 1);
+	return textLimit > 0 ? `${header}\n${excerpt(text, textLimit)}` : header;
+}