@gavin-hu/my-pi-agent 0.15.1 → 0.16.0

package/extensions/context/report.ts

@@ -0,0 +1,319 @@
+/**
+ * The pure half of the report: turn collected inputs into the numbers a reader
+ * sees, with no host access and no theme.
+ *
+ * Two rules keep the report honest. First, the headline is the host's number
+ * (`ctx.getContextUsage()`), and the composition is this module's estimate, so
+ * the difference is reported as `drift` instead of being hidden by forcing the
+ * parts to add up. Second, the compaction threshold is resolved the way the host
+ * resolves it — per-model override, then the shared setting, then Pi's default —
+ * because the point of the report is to predict when Pi will compact.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { DEFAULT_COMPACTION_SETTINGS, estimateTokens, getLatestCompactionEntry } from "@earendil-works/pi-coding-agent";
+import { sanitizeLine } from "../../lib/format.ts";
+import type {
+	CompactionHistory,
+	CompactionSummary,
+	ContextBucket,
+	ContextInputs,
+	ContextReport,
+	ContextSettings,
+	LargestBlock,
+} from "./types.ts";
+
+/** The host's chars/4 heuristic, for text that is not a `message` (system prompt, schemas). */
+export function estimateText(text: string): number {
+	return estimateChars(text.length);
+}
+
+/** {@link estimateText} when only a character count is known, without building the string. */
+export function estimateChars(chars: number): number {
+	return Math.ceil(chars / 4);
+}
+
+/** The compaction numbers in effect for one model. */
+export interface ResolvedCompaction {
+	enabled: boolean;
+	reserve: number;
+	keepRecentTokens: number;
+}
+
+/** A token setting as the host reads it: a finite, non-negative whole number. */
+function tokenSetting(value: number | undefined, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return fallback;
+	return Math.floor(value);
+}
+
+/**
+ * Resolve the compaction settings for `model` exactly as Pi does:
+ * `compaction.modelOverrides["provider/id"]`, then `compaction`, then the default.
+ */
+export function resolveCompactionSettings(
+	settings: ContextSettings,
+	model: { provider: string; id: string } | null,
+): ResolvedCompaction {
+	const compaction = settings.compaction;
+	const override = model ? compaction?.modelOverrides?.[`${model.provider}/${model.id}`] : undefined;
+	return {
+		enabled: compaction?.enabled ?? DEFAULT_COMPACTION_SETTINGS.enabled,
+		reserve: tokenSetting(
+			override?.reserveTokens,
+			tokenSetting(compaction?.reserveTokens, DEFAULT_COMPACTION_SETTINGS.reserveTokens),
+		),
+		keepRecentTokens: tokenSetting(
+			override?.keepRecentTokens,
+			tokenSetting(compaction?.keepRecentTokens, DEFAULT_COMPACTION_SETTINGS.keepRecentTokens),
+		),
+	};
+}
+
+/** A message's role; custom roles are matched by name, never by a host type. */
+function roleOf(message: AgentMessage): string {
+	const role = (message as { role?: unknown }).role;
+	return typeof role === "string" ? role : "";
+}
+
+/** The `customType` an injected message carries; the pack tags every injection. */
+function customTypeOf(message: AgentMessage): string {
+	const customType = (message as { customType?: unknown }).customType;
+	return typeof customType === "string" && customType.trim() ? sanitizeLine(customType) : "injected";
+}
+
+/** The text a message's content starts with, for a descriptor. */
+function firstText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) continue;
+		if ((block as { type?: unknown }).type !== "text") continue;
+		const text = (block as { text?: unknown }).text;
+		if (typeof text === "string" && text.trim()) return text;
+	}
+	return "";
+}
+
+/** A one-line, bounded descriptor for the "largest blocks" list. */
+function boundedLabel(text: string, maxLength = 40): string {
+	const line = sanitizeLine(text);
+	return line.length > maxLength ? `${line.slice(0, maxLength - 1)}…` : line;
+}
+
+/** What kind of message a block is, in the report's vocabulary. */
+const ROLE_LABELS: Readonly<Record<string, string>> = {
+	toolResult: "tool result",
+	assistant: "assistant",
+	user: "user",
+	custom: "injected",
+	bashExecution: "shell",
+	branchSummary: "summary",
+	compactionSummary: "summary",
+	system: "system",
+};
+
+function roleLabel(message: AgentMessage): string {
+	return ROLE_LABELS[roleOf(message)] ?? "message";
+}
+
+/** The descriptor under a block's role: a tool name, a first line, a custom type. */
+function descriptorOf(message: AgentMessage): string {
+	switch (roleOf(message)) {
+		case "toolResult": {
+			const name = (message as { toolName?: unknown }).toolName;
+			return typeof name === "string" && name ? sanitizeLine(name) : "result";
+		}
+		case "custom":
+			return customTypeOf(message);
+		case "bashExecution": {
+			const command = (message as { command?: unknown }).command;
+			return boundedLabel(typeof command === "string" ? command : "command");
+		}
+		case "branchSummary":
+		case "compactionSummary": {
+			const summary = (message as { summary?: unknown }).summary;
+			return boundedLabel(typeof summary === "string" ? summary : "summary");
+		}
+		default: {
+			const text = firstText((message as { content?: unknown }).content);
+			return text ? boundedLabel(text) : roleLabel(message);
+		}
+	}
+}
+
+/** `YYYY-MM-DD HH:MMZ` from an entry's ISO timestamp, without locale formatting. */
+export function compactTimestamp(timestamp: string): string {
+	const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(timestamp);
+	return match ? `${match[1]} ${match[2]}Z` : boundedLabel(timestamp, 24);
+}
+
+/** The branch's compaction history, newest last in the entry list. */
+function compactionHistory(inputs: ContextInputs): CompactionHistory {
+	const count = inputs.branch.filter((entry) => entry.type === "compaction").length;
+	const latest = getLatestCompactionEntry(inputs.branch);
+	if (!latest) return { count, last: null };
+	const summaryTokens = estimateText(latest.summary);
+	const last: CompactionSummary = {
+		at: compactTimestamp(latest.timestamp),
+		tokensBefore: latest.tokensBefore,
+		summaryTokens,
+		freed: Math.max(0, latest.tokensBefore - summaryTokens),
+	};
+	return { count, last };
+}
+
+/** A top-level row before shares and nesting are applied. */
+interface BucketDraft {
+	id: string;
+	label: string;
+	tokens: number;
+	note?: string;
+}
+
+/** Round a share so the text and the screen cannot disagree about precision. */
+function shareOf(tokens: number, total: number): number {
+	if (total <= 0) return 0;
+	return Math.round((tokens / total) * 1000) / 10;
+}
+
+/** Build the report from collected inputs. Pure: the same inputs give the same numbers. */
+export function buildReport(inputs: ContextInputs): ContextReport {
+	const resolved = resolveCompactionSettings(inputs.settings, inputs.model);
+	const window = inputs.window > 0 ? inputs.window : (inputs.usage?.contextWindow ?? 0);
+	const tokens = inputs.usage?.tokens ?? null;
+	const percent = inputs.usage?.percent ?? (tokens !== null && window > 0 ? (tokens / window) * 100 : null);
+	const free = tokens !== null && window > 0 ? window - tokens : null;
+	const autoCompactAt = window > 0 ? Math.max(0, window - resolved.reserve) : 0;
+	const headroom = tokens !== null && free !== null && window > 0 ? autoCompactAt - tokens : null;
+
+	const messageCounts = new Map<string, number>();
+	const messageTokens = new Map<string, number>();
+	const injectedTokens = new Map<string, number>();
+	const injectedCounts = new Map<string, number>();
+	let systemTokens = 0;
+	const largestCandidates: Array<{ message: AgentMessage; tokens: number }> = [];
+
+	const add = (id: string, estimate: number): void => {
+		messageTokens.set(id, (messageTokens.get(id) ?? 0) + estimate);
+		messageCounts.set(id, (messageCounts.get(id) ?? 0) + 1);
+	};
+
+	for (const message of inputs.messages) {
+		const estimate = estimateTokens(message);
+		if (estimate > 0) largestCandidates.push({ message, tokens: estimate });
+		switch (roleOf(message)) {
+			case "system":
+				systemTokens += estimate;
+				break;
+			case "user":
+				add("user", estimate);
+				break;
+			case "assistant":
+				add("assistant", estimate);
+				break;
+			case "toolResult":
+				add("toolResults", estimate);
+				break;
+			case "custom": {
+				const customType = customTypeOf(message);
+				injectedTokens.set(customType, (injectedTokens.get(customType) ?? 0) + estimate);
+				injectedCounts.set(customType, (injectedCounts.get(customType) ?? 0) + 1);
+				break;
+			}
+			case "branchSummary":
+			case "compactionSummary":
+				add("summaries", estimate);
+				break;
+			case "bashExecution":
+				add("bash", estimate);
+				break;
+			default:
+				// Pi's estimator returns 0 for a role it does not know, so there is
+				// nothing to attribute and no row to open.
+				break;
+		}
+	}
+
+	// The host counts the system prompt once. Prefer a system message when the
+	// projection carries one, so it is never counted twice.
+	const systemEstimate = systemTokens > 0 ? systemTokens : estimateText(inputs.systemPrompt);
+
+	const top: BucketDraft[] = [];
+	const push = (id: string, label: string, estimate: number, note?: string): void => {
+		if (estimate <= 0) return;
+		top.push({ id, label, tokens: estimate, ...(note ? { note } : {}) });
+	};
+	const countNote = (count: number): string | undefined =>
+		count > 0 ? `${count} ${count === 1 ? "message" : "messages"}` : undefined;
+	const messageNote = (id: string): string | undefined => countNote(messageCounts.get(id) ?? 0);
+
+	push("system", "System prompt", systemEstimate);
+	push("tools", "Tool definitions", inputs.tools.tokens, `${inputs.tools.active} active of ${inputs.tools.total}`);
+	push("user", "User messages", messageTokens.get("user") ?? 0, messageNote("user"));
+	push("assistant", "Assistant", messageTokens.get("assistant") ?? 0, messageNote("assistant"));
+	push("toolResults", "Tool results", messageTokens.get("toolResults") ?? 0, messageNote("toolResults"));
+
+	const injectedTotal = [...injectedTokens.values()].reduce((sum, value) => sum + value, 0);
+	const injectedCount = [...injectedCounts.values()].reduce((sum, value) => sum + value, 0);
+	push("injected", "Injected context", injectedTotal, countNote(injectedCount));
+
+	push("summaries", "Summaries", messageTokens.get("summaries") ?? 0, messageNote("summaries"));
+	push("bash", "Shell output", messageTokens.get("bash") ?? 0, messageNote("bash"));
+
+	const estimate = top.reduce((sum, bucket) => sum + bucket.tokens, 0);
+
+	// Injected children: per custom type, biggest first, then one "other" row so
+	// the child list stays short without dropping a type's share.
+	const children = [...injectedTokens.entries()].sort((a, b) => b[1] - a[1]);
+	const shown = children.slice(0, 5);
+	const rest = children.slice(5);
+	const childDrafts: BucketDraft[] = shown.map(([customType, estimateForType]) => ({
+		id: `injected:${customType}`,
+		label: customType,
+		tokens: estimateForType,
+		note: countNote(injectedCounts.get(customType) ?? 0),
+	}));
+	if (rest.length > 0) {
+		childDrafts.push({
+			id: "injected:other",
+			label: `${rest.length} more`,
+			tokens: rest.reduce((sum, [, value]) => sum + value, 0),
+			note: countNote(rest.reduce((sum, [type]) => sum + (injectedCounts.get(type) ?? 0), 0)),
+		});
+	}
+
+	const buckets: ContextBucket[] = [];
+	for (const draft of top) {
+		buckets.push({ ...draft, share: shareOf(draft.tokens, estimate), depth: 0 });
+		if (draft.id !== "injected") continue;
+		for (const child of childDrafts) {
+			buckets.push({ ...child, share: shareOf(child.tokens, estimate), depth: 1 });
+		}
+	}
+
+	const largest: LargestBlock[] = largestCandidates
+		.sort((a, b) => b.tokens - a.tokens)
+		.slice(0, 5)
+		.map((candidate) => ({
+			tokens: candidate.tokens,
+			role: roleLabel(candidate.message),
+			label: descriptorOf(candidate.message),
+		}));
+
+	return {
+		window,
+		tokens,
+		percent,
+		free,
+		headroom,
+		reserve: resolved.reserve,
+		keepRecentTokens: resolved.keepRecentTokens,
+		enabled: resolved.enabled,
+		autoCompactAt,
+		buckets,
+		estimate,
+		drift: tokens !== null ? tokens - estimate : null,
+		compaction: compactionHistory(inputs),
+		largest,
+	};
+}

package/extensions/context/tui.ts

@@ -0,0 +1,268 @@
+/**
+ * The `/context` screen: one docked report, with the one action the report
+ * justifies.
+ *
+ * The component owns the scroll, the confirm layer, and the feedback line; it
+ * owns no host access. The command hands it a report and two callbacks (`read`
+ * and `compact`), which keeps the screen testable with a plain object and keeps
+ * the host boundary in `collect.ts` / `commands.ts`.
+ *
+ * The report is re-read on open, on `r`, and after a compaction — never per
+ * frame. Arrow keys only move a slice of a body that is already built, so a
+ * long session does not re-walk its entries on every keypress.
+ */
+
+import type { CompactionResult, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { messageOf } from "../../lib/errors.ts";
+import { formatTokens } from "../../lib/format.ts";
+import { screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { ConfirmState } from "../../lib/tui/confirm.ts";
+import { clampScroll, fitRows, formatRange, isCloseKey, navigateScroll } from "../../lib/tui/cursor.ts";
+import { gaugeBar, gaugeRole } from "../../lib/tui/gauge.ts";
+import { BODY_INDENT } from "../../lib/tui/indent.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
+import { formatBudget, formatCompaction, formatDrift } from "./format.ts";
+import type { ContextBucket, ContextReport } from "./types.ts";
+
+/** Fixed rows around the scrollable body: title, gauge, budget, blank, blank, footer, blank. */
+const CHROME_ROWS = 7;
+
+/** Cells in the composition bar. */
+const BUCKET_BLOCKS = 8;
+
+/** Body rows when the terminal height is unknown. */
+const DEFAULT_BODY_ROWS = 12;
+
+/** What the compact action needs from the screen. */
+export interface ContextCompactCallbacks {
+	done(result: CompactionResult): void;
+	fail(error: unknown): void;
+}
+
+/** Everything the screen needs; the command supplies the host work. */
+export interface ContextScreenOptions {
+	theme: Theme;
+	/** The report as opened. */
+	report: ContextReport;
+	/** Re-collect and rebuild the report. */
+	read(): ContextReport;
+	/** Whether the agent is busy (a turn or a compaction); compaction is refused while it is. */
+	isIdle(): boolean;
+	/** Start the host's compaction with custom instructions, or the plain one. */
+	compact(instructions: string | undefined, callbacks: ContextCompactCallbacks): void;
+	/** Close the screen. */
+	close(): void;
+	/** Ask the host to repaint. */
+	requestRender(): void;
+	/** Terminal height, read fresh so a resize is picked up. */
+	viewportRowsSource?: ViewportRowsSource;
+}
+
+/** A feedback message and the role it is painted in. */
+interface Feedback {
+	text: string;
+	role: TuiRole;
+}
+
+/** A right-aligned cell in a composition row. */
+function shareCell(share: number): string {
+	return `${share.toFixed(1)}%`.padStart(6);
+}
+
+/** Pad a label to its column with spaces, measured in terminal columns. */
+function padCell(text: string, width: number): string {
+	const clipped = truncateToWidth(text, width, "…");
+	return `${clipped}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+}
+
+/** The scrollable, read-only report. */
+export class ContextComponent implements Component {
+	private report: ContextReport;
+	private scroll = 0;
+	private visible = DEFAULT_BODY_ROWS;
+	private body: string[] = [];
+	private feedback: Feedback | undefined;
+	private readonly confirm = new ConfirmState();
+
+	constructor(private readonly options: ContextScreenOptions) {
+		this.report = options.report;
+	}
+
+	private get theme(): Theme {
+		return this.options.theme;
+	}
+
+	/** Replace the report from the host and repaint. */
+	private refresh(): void {
+		this.report = this.options.read();
+		this.requestRender();
+	}
+
+	private requestRender(): void {
+		this.options.requestRender();
+	}
+
+	private setFeedback(text: string, role: TuiRole): void {
+		this.feedback = { text, role };
+		this.requestRender();
+	}
+
+	/** Ask before compacting, then run the action only once the turn is idle. */
+	private askCompact(): void {
+		this.confirm.ask("Compact the conversation now? y/N", () => {
+			if (!this.options.isIdle()) {
+				this.setFeedback("The agent is busy (a turn or a compaction is running); wait for it to finish.", "warn");
+				return;
+			}
+			this.feedback = { text: "Compacting…", role: "meta" };
+			this.requestRender();
+			this.options.compact(undefined, {
+				done: (result) => {
+					this.report = this.options.read();
+					const after = result.estimatedTokensAfter === undefined ? "?" : formatTokens(result.estimatedTokensAfter);
+					this.setFeedback(`Compacted ${formatTokens(result.tokensBefore)} → ${after}`, "ok");
+				},
+				fail: (error) => {
+					this.setFeedback(`Compaction failed: ${messageOf(error)}`, "bad");
+				},
+			});
+		});
+		this.requestRender();
+	}
+
+	/** The gauge line: the host's number, its bar, and its percentage. */
+	private gaugeLine(width: number): string {
+		const { percent, tokens, window } = this.report;
+		if (window <= 0) return truncateToWidth(`  ${paint(this.theme, "meta", "no model context window")}`, width);
+		const role = gaugeRole(percent);
+		const value = tokens === null ? `? / ${formatTokens(window)}` : `${formatTokens(tokens)} / ${formatTokens(window)}`;
+		const bar = gaugeBar(this.theme, { percent, blocks: 10 });
+		const label = percent === null ? "unknown" : `${Math.round(percent)}%`;
+		return truncateToWidth(`  ${paint(this.theme, role, value)}  ${bar}  ${paint(this.theme, role, label)}`, width);
+	}
+
+	/** One composition row; optional columns drop as the terminal narrows. */
+	private bucketLine(bucket: ContextBucket, width: number): string {
+		const indent = " ".repeat(bucket.depth > 0 ? 4 : 2);
+		const labelWidth = bucket.depth > 0 ? 16 : 18;
+		const label = padCell(bucket.label, labelWidth);
+		const tokens = formatTokens(bucket.tokens).padStart(6);
+		const share = shareCell(bucket.share);
+		const note = bucket.note ? `  ${bucket.note}` : "";
+		const bar = gaugeBar(this.theme, {
+			percent: bucket.share,
+			blocks: BUCKET_BLOCKS,
+			role: "meta",
+			emptyRole: "faint",
+		});
+		const head = `${indent}${paint(this.theme, "label", label)}${paint(this.theme, "meta", tokens)}`;
+		// Keep the tokens and the label above a trailing note, then the percentage,
+		// then the bar, so a narrow terminal still reads "what" and "how much".
+		const candidates = [`${head}  ${share}  ${bar}${note}`, `${head}  ${share}${note}`, `${head}${note}`, head];
+		for (const candidate of candidates) {
+			if (visibleWidth(candidate) <= width) return candidate;
+		}
+		return truncateToWidth(head, width);
+	}
+
+	/** The scrollable body: composition, drift, compaction, and the largest blocks. */
+	private buildBody(width: number): string[] {
+		const report = this.report;
+		const lines: string[] = report.buckets.map((bucket) => this.bucketLine(bucket, width));
+
+		const drift = formatDrift(report);
+		if (drift) lines.push("", truncateToWidth(`  ${paint(this.theme, "warn", drift)}`, width));
+
+		lines.push(
+			"",
+			truncateToWidth(
+				`  ${paint(this.theme, "label", "Compaction")}  ${paint(this.theme, "meta", formatCompaction(report))}`,
+				width,
+			),
+		);
+
+		if (report.largest.length > 0) {
+			lines.push("", `  ${paint(this.theme, "label", "Largest blocks")}`);
+			for (const block of report.largest) {
+				const tokens = formatTokens(block.tokens).padStart(6);
+				const role = padCell(block.role, 11);
+				const candidate = `    ${paint(this.theme, "meta", tokens)}  ${paint(this.theme, "label", role)}${block.label}`;
+				lines.push(truncateToWidth(candidate, width));
+			}
+		}
+		return lines;
+	}
+
+	/** The footer: a feedback line, the pending confirmation, or the key hints. */
+	private footerLine(width: number): string {
+		const pending = this.confirm.pending;
+		if (pending) return truncateToWidth(`  ${paint(this.theme, "warn", pending.prompt)}`, width);
+		if (this.feedback) return truncateToWidth(`  ${paint(this.theme, this.feedback.role, this.feedback.text)}`, width);
+		return screenHint(
+			this.theme,
+			width,
+			[
+				{ text: "c compact", color: "accent" },
+				{ text: "r refresh", color: "dim" },
+				{ text: "↑↓ scroll", color: "dim" },
+				{ text: "Esc close", color: "dim" },
+			],
+			BODY_INDENT,
+		);
+	}
+
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		this.body = this.buildBody(w);
+		this.visible = fitRows(this.options.viewportRowsSource, this.body.length, CHROME_ROWS, DEFAULT_BODY_ROWS);
+		this.scroll = clampScroll(this.scroll, this.body.length, this.visible);
+
+		const end = Math.min(this.body.length, this.scroll + this.visible);
+		const lines = [
+			titleRule(this.theme, w, "Context"),
+			this.gaugeLine(w),
+			truncateToWidth(`  ${paint(this.theme, "meta", formatBudget(this.report))}`, w),
+			"",
+			...this.body.slice(this.scroll, end),
+		];
+		if (this.body.length > this.visible) {
+			lines.push(formatRange(this.theme, w, { start: this.scroll, end, total: this.body.length }));
+		}
+		lines.push("", this.footerLine(w), "");
+		return lines.map((line) => truncateToWidth(line, w));
+	}
+
+	handleInput(data: string): void {
+		const outcome = this.confirm.resolve(data);
+		if (outcome) {
+			this.requestRender();
+			return;
+		}
+		if (data === "g" || data === "G") {
+			this.scroll = data === "g" ? 0 : Math.max(0, this.body.length - this.visible);
+			this.requestRender();
+			return;
+		}
+		const next = navigateScroll(data, this.scroll, this.body.length, this.visible);
+		if (next !== undefined) {
+			this.scroll = next;
+			this.requestRender();
+			return;
+		}
+		if (data === "c") {
+			this.askCompact();
+			return;
+		}
+		if (data === "r") {
+			this.feedback = { text: "Refreshed.", role: "meta" };
+			this.refresh();
+			return;
+		}
+		if (isCloseKey(data) || data === "q") this.options.close();
+	}
+
+	/** A read-only report caches nothing, so a theme change has nothing to drop. */
+	invalidate(): void {}
+}