pi-posthorse 0.8.0 → 0.8.2

package/src/ui/cards.ts

@@ -0,0 +1,355 @@
+import type { Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import {
+	displayOf,
+	displaySummary,
+	historySections,
+	pageSummary,
+	summaryOnly,
+	type HistorySection,
+	type PosthorseDisplay,
+} from "./display.ts";
+import { argsOf, argument, clean, hint, textBlock, textOf, type OutputColor } from "./text.ts";
+
+export type ToolName = "notes" | "history" | "get_context_remaining" | "new_context";
+const titles: Readonly<Record<ToolName, string>> = {
+	notes: "Notes",
+	history: "History",
+	get_context_remaining: "Context budget",
+	new_context: "New context",
+};
+const n = (value: number): string => value.toLocaleString("en-US");
+
+interface CallState {
+	readonly isError: boolean;
+	readonly isPartial: boolean;
+	readonly executionStarted: boolean;
+	readonly expanded: boolean;
+}
+
+function callTarget(name: ToolName, args: Readonly<Record<string, unknown>>): string {
+	if (args.op === "search") {
+		return ` · “${argument(args.query, "query")}”`;
+	}
+	if (name === "notes" && (args.op !== "list" || args.path !== undefined)) {
+		return ` · ${argument(args.path, "path")}`;
+	}
+	return name === "history" && args.op === "read" ? ` · ${argument(args.id, "id")}` : "";
+}
+
+function callStatus(state: CallState): string {
+	if (state.isError) {
+		return " · error";
+	}
+	if (!state.isPartial) {
+		return "";
+	}
+	return state.executionStarted ? " · running" : " · preparing";
+}
+
+function callDetails(name: ToolName, args: Readonly<Record<string, unknown>>): string {
+	const scope =
+		name === "history" && args.op === "search"
+			? `Scope: ${args.all === true ? "all project sessions" : "current branch"}`
+			: "";
+	const offsets = [
+		["offset", "Offset"],
+		["imageOffset", "Image offset"],
+		["limit", "Limit"],
+	].map(([key, label]) => {
+		const value = args[key];
+		return value === undefined
+			? ""
+			: `${label}: ${typeof value === "number" ? n(value) : `[invalid ${key}]`}`;
+	});
+	return [scope, ...offsets].filter((part) => part.length > 0).join(" · ");
+}
+
+function callComponent(
+	name: ToolName,
+	args: Readonly<Record<string, unknown>>,
+	theme: Theme,
+	state: CallState,
+): Component {
+	let action = "";
+	if (name === "notes" || name === "history") {
+		action = ` · ${argument(args.op, "op")}`;
+	} else if (name === "new_context") {
+		action = " · request";
+	}
+	let marker = "▸";
+	if (state.isPartial) {
+		marker = "…";
+	} else if (state.expanded) {
+		marker = "▾";
+	}
+	const label = `${marker} ${titles[name]}${action}${callStatus(state)}${callTarget(name, args)}`;
+	return {
+		invalidate() {
+			// Stateless layout is recomputed with the current width on every render.
+		},
+		render(width) {
+			const heading = theme.fg(state.isError ? "error" : "toolTitle", theme.bold(label));
+			if (!state.expanded) {
+				return [truncateToWidth(heading.replace(/\s+/g, " "), width)];
+			}
+			return [
+				...new Text(heading, 0, 0).render(width),
+				...textBlock(callDetails(name, args), theme, "muted").render(width),
+			];
+		},
+	};
+}
+
+interface ResultFacts {
+	readonly name: ToolName;
+	readonly raw: string;
+	readonly args: Readonly<Record<string, unknown>>;
+	readonly display: PosthorseDisplay | undefined;
+	readonly isError: boolean;
+	readonly isPartial: boolean;
+	readonly expanded: boolean;
+	readonly imageCount: number;
+	readonly showImages: boolean;
+}
+
+function submittedText(facts: ResultFacts): string {
+	const { name, args } = facts;
+	if (name === "new_context" && typeof args.handoff === "string") {
+		return `Handoff supplied:\n${args.handoff}`;
+	}
+	if (
+		name === "notes" &&
+		(args.op === "write" || args.op === "append") &&
+		typeof args.content === "string"
+	) {
+		return `Submitted content:\n${args.content.length > 0 ? args.content : "(empty)"}`;
+	}
+	return "";
+}
+
+function resultSummary(
+	facts: ResultFacts,
+	sections: readonly HistorySection[] | undefined,
+): string {
+	if (facts.isError || facts.isPartial) {
+		return "";
+	}
+	const { display } = facts;
+	const summary = displaySummary(display, facts.args, sections !== undefined);
+	if (
+		(display?.kind === "notes-list" || display?.kind === "notes-search") &&
+		display.page !== undefined &&
+		(display.page.offset > 0 || display.page.end < display.page.total)
+	) {
+		return `${summary}\n${pageSummary(display.page, display.more)}`;
+	}
+	return summary;
+}
+
+function resultColor(facts: ResultFacts): OutputColor {
+	if (facts.isError) {
+		return "error";
+	}
+	const { display } = facts;
+	if (facts.isPartial || display?.kind !== "context" || display.rollover !== "unsupported") {
+		return "toolOutput";
+	}
+	const tokens = display.usage?.tokens;
+	return tokens !== undefined && tokens !== null ? "warning" : "toolOutput";
+}
+
+function resultBody(facts: ResultFacts): string {
+	if (facts.raw.trim().length > 0) {
+		return facts.raw;
+	}
+	if (facts.isError) {
+		return "No error details returned.";
+	}
+	if (facts.isPartial) {
+		return "Running…";
+	}
+	return facts.name === "notes" && facts.args.op === "read" ? "Empty note" : "No text returned.";
+}
+
+function noteHeaderLength(facts: ResultFacts): number {
+	const { display } = facts;
+	return !facts.isError && (display?.kind === "note-read" || display?.kind === "notes-list")
+		? (display.headerLength ?? 0)
+		: 0;
+}
+
+function previewBody(facts: ResultFacts, sections: readonly HistorySection[] | undefined): string {
+	if (sections !== undefined) {
+		return sections.map(({ body }) => body).join("\n");
+	}
+	const body = resultBody(facts);
+	const headerLength = noteHeaderLength(facts);
+	if (headerLength > 0) {
+		return body.slice(headerLength);
+	}
+	// Old results have no spans. Only the preview sheds the known history prefix.
+	return facts.name === "history" && !facts.isError
+		? body.replace(
+				/^[^\n]*?\[window [^\]\n]+\] \[[^\]\n]+\](?: \[chars \d+-\d+ of \d+\])? /gm,
+				"",
+			)
+		: body;
+}
+
+interface ResultLayout {
+	readonly full: Component;
+	readonly summary: Component;
+	readonly preview: Component;
+	readonly submitted: Component;
+	readonly attachment: string;
+	readonly attachmentBlock: Component;
+	readonly footer: Component;
+	readonly searchPreviews: readonly string[] | undefined;
+	readonly hasDetails: boolean;
+}
+
+function resultLayout(
+	facts: ResultFacts,
+	sections: readonly HistorySection[] | undefined,
+	theme: Theme,
+): ResultLayout {
+	const color = resultColor(facts);
+	const submission = submittedText(facts);
+	const attachment = attachmentSummary(facts);
+	const { display } = facts;
+	const footerLength = display?.kind === "history-search" ? (display.footerLength ?? 0) : 0;
+	return {
+		full: fullBody(facts, sections, theme),
+		summary: textBlock(resultSummary(facts, sections), theme, color),
+		preview: textBlock(previewBody(facts, sections), theme, color),
+		submitted: textBlock(submission, theme),
+		attachment,
+		attachmentBlock: textBlock(attachment, theme, "muted"),
+		footer: textBlock(
+			sections !== undefined && footerLength > 0 ? facts.raw.slice(-footerLength) : "",
+			theme,
+			"muted",
+		),
+		searchPreviews: searchPreviews(facts, sections, theme),
+		hasDetails: sections !== undefined || submission.length > 0 || noteHeaderLength(facts) > 0,
+	};
+}
+
+function attachmentSummary(facts: ResultFacts): string {
+	if (facts.imageCount === 0) {
+		return "";
+	}
+	return `${facts.imageCount} image${facts.imageCount === 1 ? "" : "s"} attached${facts.showImages ? "" : " (display hidden)"}`;
+}
+
+function fullBody(
+	facts: ResultFacts,
+	sections: readonly HistorySection[] | undefined,
+	theme: Theme,
+): Component {
+	if (sections === undefined) {
+		return textBlock(resultBody(facts), theme, resultColor(facts));
+	}
+	return new Text(
+		sections
+			.map(
+				({ body, header }) =>
+					`${theme.fg("toolOutput", clean(body))}\n${theme.fg("dim", clean(header))}`,
+			)
+			.join("\n\n"),
+		0,
+		0,
+	);
+}
+
+function searchPreviews(
+	facts: ResultFacts,
+	sections: readonly HistorySection[] | undefined,
+	theme: Theme,
+): readonly string[] | undefined {
+	return sections !== undefined && facts.display?.kind === "history-search"
+		? sections
+				.slice(0, 3)
+				.map(({ body }) => theme.fg("toolOutput", clean(body).replace(/\s+/g, " ")))
+		: undefined;
+}
+
+function previewRows(facts: ResultFacts, layout: ResultLayout, width: number): string[] {
+	if (summaryOnly(facts.display) && !facts.isError && !facts.isPartial) {
+		return [];
+	}
+	return (
+		layout.searchPreviews?.map((line) => truncateToWidth(line, width)) ??
+		layout.preview.render(width)
+	);
+}
+
+function collapsedRows(
+	facts: ResultFacts,
+	layout: ResultLayout,
+	theme: Theme,
+	width: number,
+): string[] {
+	const summaryRows = layout.summary.render(width).slice(0, 5);
+	const previews = previewRows(facts, layout, width);
+	const shown = previews.slice(
+		0,
+		Math.max(0, Math.min(3, 5 - summaryRows.length - (layout.attachment.length > 0 ? 1 : 0))),
+	);
+	const hidden =
+		summaryOnly(facts.display) || previews.length > shown.length || layout.hasDetails;
+	const attachments =
+		layout.attachment.length > 0
+			? [truncateToWidth(theme.fg("muted", layout.attachment), width)]
+			: [];
+	return [...summaryRows, ...shown, ...attachments, ...(hidden ? [hint(theme, width)] : [])];
+}
+
+function resultComponent(facts: ResultFacts, theme: Theme): Component {
+	const sections =
+		!facts.isError && !facts.isPartial ? historySections(facts.raw, facts.display) : undefined;
+	const layout = resultLayout(facts, sections, theme);
+	return {
+		invalidate() {
+			// Pi creates this presentation for each result/theme update; it keeps no width cache.
+		},
+		render(width) {
+			if (facts.expanded) {
+				const submitted =
+					submittedText(facts).length > 0 ? ["", ...layout.submitted.render(width)] : [];
+				return [
+					...layout.full.render(width),
+					...layout.attachmentBlock.render(width),
+					...layout.footer.render(width),
+					...submitted,
+				];
+			}
+			return collapsedRows(facts, layout, theme, width);
+		},
+	};
+}
+
+export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "renderResult"> {
+	return {
+		renderCall(rawArgs, theme, context) {
+			return callComponent(name, argsOf(rawArgs), theme, context);
+		},
+		renderResult(result, { expanded, isPartial }, theme, context) {
+			return resultComponent(
+				{
+					name,
+					raw: textOf(result.content),
+					args: argsOf(context.args),
+					display: displayOf(result.details),
+					isError: context.isError,
+					isPartial,
+					expanded,
+					imageCount: result.content.filter((part) => part.type === "image").length,
+					showImages: context.showImages,
+				},
+				theme,
+			);
+		},
+	};
+}

package/src/ui/display.ts

@@ -0,0 +1,312 @@
+import { isRecord } from "./text.ts";
+
+export interface PageRange {
+	readonly offset: number;
+	readonly end: number;
+	readonly total: number;
+}
+
+export interface HistorySpan {
+	readonly headerLength: number;
+	readonly length: number;
+}
+
+/** Display-only facts and offsets into content, never a second copy of a note or history page. */
+export type PosthorseDisplay =
+	| {
+			readonly kind: "context";
+			readonly usage?: {
+				readonly tokens: number | null;
+				readonly contextWindow: number;
+				readonly percent: number | null;
+			};
+			readonly rollover?: "enabled" | "disabled" | "unsupported";
+			readonly rolloverAt?: number;
+	  }
+	| {
+			readonly kind: "notes-list" | "notes-search";
+			readonly count: number;
+			readonly headerLength?: number;
+			readonly page?: PageRange;
+			/** More matches follow; `page.total` counts only those found so far. */
+			readonly more?: boolean;
+	  }
+	| ({ readonly kind: "note-read"; readonly headerLength?: number } & PageRange)
+	| { readonly kind: "note-write" | "note-append" | "new-context" }
+	| {
+			readonly kind: "history-search";
+			readonly entries: readonly HistorySpan[];
+			readonly footerLength?: number;
+			readonly more?: boolean;
+			readonly skipped?: number;
+	  }
+	| ({
+			readonly kind: "history-read";
+			readonly headerLength: number;
+			readonly imageOffset?: number;
+			readonly imageEnd?: number;
+			readonly imageTotal?: number;
+	  } & PageRange);
+
+function optionalNumbers(
+	value: Readonly<Record<string, unknown>>,
+	keys: readonly string[],
+): boolean {
+	return keys.every((key) => value[key] === undefined || typeof value[key] === "number");
+}
+
+function isPage(value: unknown): value is PageRange {
+	return (
+		isRecord(value) &&
+		typeof value.offset === "number" &&
+		typeof value.end === "number" &&
+		typeof value.total === "number"
+	);
+}
+
+function isSpan(value: unknown): value is HistorySpan {
+	return (
+		isRecord(value) &&
+		typeof value.headerLength === "number" &&
+		typeof value.length === "number"
+	);
+}
+
+function isContextDisplay(value: Readonly<Record<string, unknown>>): boolean {
+	const usage = value.usage;
+	const validUsage = usage === undefined || isUsage(usage);
+	return (
+		validUsage &&
+		optionalNumbers(value, ["rolloverAt"]) &&
+		(value.rollover === undefined ||
+			value.rollover === "enabled" ||
+			value.rollover === "disabled" ||
+			value.rollover === "unsupported")
+	);
+}
+
+function isUsage(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		(value.tokens === null || typeof value.tokens === "number") &&
+		typeof value.contextWindow === "number" &&
+		(value.percent === null || typeof value.percent === "number")
+	);
+}
+
+function isSearchDisplay(value: Readonly<Record<string, unknown>>): boolean {
+	return (
+		Array.isArray(value.entries) &&
+		value.entries.every(isSpan) &&
+		optionalNumbers(value, ["footerLength", "skipped"]) &&
+		(value.more === undefined || typeof value.more === "boolean")
+	);
+}
+
+function isNotesDisplay(value: Readonly<Record<string, unknown>>): boolean {
+	return (
+		typeof value.count === "number" &&
+		optionalNumbers(value, ["headerLength"]) &&
+		(value.page === undefined || isPage(value.page)) &&
+		(value.more === undefined || typeof value.more === "boolean")
+	);
+}
+
+function isDisplay(value: unknown): value is PosthorseDisplay {
+	if (!isRecord(value)) {
+		return false;
+	}
+	switch (value.kind) {
+		case "context":
+			return isContextDisplay(value);
+		case "notes-list":
+		case "notes-search":
+			return isNotesDisplay(value);
+		case "note-read":
+			return isPage(value) && optionalNumbers(value, ["headerLength"]);
+		case "history-read":
+			return (
+				isPage(value) &&
+				typeof value.headerLength === "number" &&
+				optionalNumbers(value, ["imageOffset", "imageEnd", "imageTotal"])
+			);
+		case "history-search":
+			return isSearchDisplay(value);
+		case "note-write":
+		case "note-append":
+		case "new-context":
+			return true;
+		default:
+			return false;
+	}
+}
+
+/** Saved sessions and streamed tool results can predate the display contract. */
+export function displayOf(value: unknown): PosthorseDisplay | undefined {
+	return isDisplay(value) ? value : undefined;
+}
+
+export interface HistorySection {
+	readonly body: string;
+	readonly header: string;
+}
+
+function spansOf(
+	raw: string,
+	display: PosthorseDisplay | undefined,
+): readonly HistorySpan[] | undefined {
+	if (display?.kind === "history-search") {
+		return display.entries;
+	}
+	if (display?.kind === "history-read") {
+		return [{ headerLength: display.headerLength, length: raw.length }];
+	}
+	return undefined;
+}
+
+export function historySections(
+	raw: string,
+	display: PosthorseDisplay | undefined,
+): readonly HistorySection[] | undefined {
+	const spans = spansOf(raw, display);
+	if (spans === undefined || spans.length === 0) {
+		return undefined;
+	}
+	const footerLength = display?.kind === "history-search" ? (display.footerLength ?? 0) : 0;
+	if (!validFooter(footerLength, raw.length)) {
+		return undefined;
+	}
+	const bodyLength = raw.length - footerLength;
+	let start = 0;
+	const sections: HistorySection[] = [];
+	for (const span of spans) {
+		if (!validSpan(span, start, bodyLength)) {
+			return undefined;
+		}
+		sections.push({
+			header: raw.slice(start, start + span.headerLength).trimEnd(),
+			body: raw.slice(start + span.headerLength, start + span.length),
+		});
+		start += span.length + 1;
+	}
+	return start === bodyLength + 1 ? sections : undefined;
+}
+
+function validFooter(length: number, rawLength: number): boolean {
+	return Number.isInteger(length) && length >= 0 && length <= rawLength;
+}
+
+function validSpan(span: HistorySpan, start: number, bodyLength: number): boolean {
+	return (
+		Number.isInteger(span.headerLength) &&
+		Number.isInteger(span.length) &&
+		span.headerLength >= 0 &&
+		span.headerLength <= span.length &&
+		start + span.length <= bodyLength
+	);
+}
+
+const n = (value: number): string => value.toLocaleString("en-US");
+
+export function pageSummary(page: PageRange, more = false): string {
+	if (page.total === 0) {
+		return "Empty note";
+	}
+	if (page.offset === 0 && page.end === page.total) {
+		return `${n(page.total)} chars · complete`;
+	}
+	return `Chars ${n(page.offset)}–${n(page.end)} of ${n(page.total)}${more ? "+" : ""}${page.end < page.total ? `\nNext offset ${n(page.end)}` : " · final page"}`;
+}
+
+function contextSummary(display: Extract<PosthorseDisplay, { readonly kind: "context" }>): string {
+	const usage = display.usage;
+	if (usage === undefined || usage.tokens === null) {
+		return "Context usage unknown";
+	}
+	const configured = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens to configured context limit`;
+	const rollover =
+		display.rollover === "enabled" && display.rolloverAt !== undefined
+			? `≈${n(Math.max(0, display.rolloverAt - usage.tokens))} tokens to rollover`
+			: `Automatic rollover ${display.rollover ?? "unknown"}`;
+	return `${rollover}\n${configured}\n≈${n(usage.tokens)} / ${n(usage.contextWindow)} used${usage.percent === null ? "" : ` (≈${Math.round(usage.percent)}%)`}`;
+}
+
+function historyReadSummary(
+	display: Extract<PosthorseDisplay, { readonly kind: "history-read" }>,
+): string {
+	if (
+		display.imageTotal === undefined ||
+		display.imageTotal === 0 ||
+		display.imageEnd === undefined
+	) {
+		return pageSummary(display);
+	}
+	const summary = `${pageSummary(display).split("\n")[0]}\nImages ${n(display.imageOffset ?? 0)}–${n(display.imageEnd)} of ${n(display.imageTotal)}`;
+	return display.end < display.total || display.imageEnd < display.imageTotal
+		? `Next offset ${n(display.end)}\nimageOffset ${n(display.imageEnd)}\n${summary}`
+		: summary;
+}
+
+function historySearchSummary(
+	display: Extract<PosthorseDisplay, { readonly kind: "history-search" }>,
+	all: boolean,
+	validSections: boolean,
+): string {
+	if (display.entries.length > 0 && !validSections) {
+		return "";
+	}
+	const skipped = display.skipped ?? 0;
+	const more = display.more ?? (display.footerLength ?? 0) > 0;
+	return `${display.entries.length > 0 ? `${n(display.entries.length)} matches` : "No matches"} · ${all ? "all sessions" : "current branch"}${skipped > 0 ? ` · ${n(skipped)} in context skipped` : ""}${more ? "\nMore results; continue with cursor" : ""}`;
+}
+
+export function displaySummary(
+	display: PosthorseDisplay | undefined,
+	args: Readonly<Record<string, unknown>>,
+	validSections: boolean,
+): string {
+	switch (display?.kind) {
+		case "context":
+			return contextSummary(display);
+		case "notes-list":
+			return display.count > 0
+				? `${n(display.count)} note${display.count === 1 ? "" : "s"} returned`
+				: "No notes yet";
+		case "notes-search":
+			return display.count > 0 ? `${n(display.count)} matches returned` : "No matches";
+		case "note-read":
+			return pageSummary(display);
+		case "note-write":
+			return args.content === "" ? "Cleared note" : "Saved note";
+		case "note-append":
+			return "Appended to note";
+		case "history-search":
+			return historySearchSummary(display, args.all === true, validSections);
+		case "history-read":
+			return historyReadSummary(display);
+		case "new-context":
+			return "Requested after foreground tools succeed.\nBackground work continues.";
+		case undefined:
+			return "";
+	}
+}
+
+export function summaryOnly(display: PosthorseDisplay | undefined): boolean {
+	switch (display?.kind) {
+		case "context":
+		case "new-context":
+		case "note-write":
+		case "note-append":
+			return true;
+		case "notes-list":
+		case "notes-search":
+			return display.count === 0;
+		case "note-read":
+			return display.total === 0;
+		case "history-search":
+			return display.entries.length === 0;
+		case "history-read":
+		case undefined:
+			return false;
+	}
+}