pi-bar 0.3.5 → 0.3.7

package/README.md

@@ -3,22 +3,23 @@
 [![npm version](https://img.shields.io/npm/v/pi-bar.svg)](https://www.npmjs.com/package/pi-bar)
 [![npm downloads](https://img.shields.io/npm/dm/pi-bar.svg)](https://www.npmjs.com/package/pi-bar)
 
-**Never accidentally run Opus on a typo again.** pi-bar puts the active model, thinking level, context usage, and extension statuses in pi's footer so you catch wrong-model / wrong-reasoning / context-pressure problems before they cost you.
+**Never accidentally run Opus on a typo again.** pi-bar puts the active model, thinking level, context usage, live TLDR, and extension statuses in pi's footer so you catch wrong-model / wrong-reasoning / context-pressure problems before they cost you.
 
 ```text
-◈ claude-opus-4.7  ❯  ✦ think:med  ❯  ◷ 2.6% / 1.0M  ❯  ✧ plan:active
+◈ claude-opus-4.7  ❯  ✦ think:med  ❯  ◷ 2.6% / 1.0M  ❯  ⓘ Inspecting package structure  ❯  ✧ plan:active
 ```
 
-![pi-bar screenshot, three rows showing green, yellow, and red context usage](https://cdn.jsdelivr.net/npm/pi-bar@0.3.5/assets/screenshot.png)
+![pi-bar screenshot, three rows showing green, yellow, and red context usage](https://cdn.jsdelivr.net/npm/pi-bar@0.3.7/assets/screenshot.png)
 
 ## Why use it?
 
 - **See the active model at a glance** — catch accidental model switches before an expensive or sensitive task starts.
 - **Track thinking level in place** — immediately notice when you are using the wrong reasoning setting.
 - **Watch context pressure early** — context usage turns green, yellow, then red as you approach the limit.
+- **Show live TLDR inline** — pi-bar can generate a compact live summary directly in the footer.
 - **Keep extension statuses visible** — statuses set with `ctx.ui.setStatus()` still appear in the custom footer.
 
-pi-bar is intentionally tiny: one small extension, no broad behavior changes, and no commands to learn. It replaces pi's built-in footer with a compact model / thinking / context / extension-status line that refreshes when model, thinking level, context usage, or extension statuses change.
+pi-bar is intentionally tiny: one small extension, no broad behavior changes, and no commands to learn. It replaces pi's built-in footer with a compact model / thinking / context / tldr / extension-status line that refreshes when model, thinking level, context usage, generated TLDR, or extension statuses change.
 
 ## Install
 
@@ -39,11 +40,29 @@ pi-bar works out of the box, but you can tune it with environment variables befo
 ### Show or hide segments
 
 ```bash
-PI_BAR_SHOW=model,thinking,context,extensions pi
+PI_BAR_SHOW=model,thinking,context,tldr,extensions pi
 PI_BAR_SHOW=model,context pi
 ```
 
-Allowed segments are `model`, `thinking`, `context`, and `extensions`. The `extensions` segment is hidden when no extension has set a status.
+Allowed segments are `model`, `thinking`, `context`, `tldr`, and `extensions`. The `tldr` segment is hidden until pi-bar generates a current TLDR. The `extensions` segment is hidden when no extension has set a status.
+
+### Configure live TLDR
+
+pi-bar generates live footer TLDRs from recent prompt, assistant, tool, and result activity. It uses a fast authenticated model and stays quiet when none is available. Limit segment width with:
+
+```bash
+PI_BAR_TLDR_MAX_WIDTH=48 pi
+```
+
+Default is `64`. Set `PI_BAR_SHOW` without `tldr` to hide it.
+
+By default, pi-bar uses the first authenticated fast model from its fallback list. Override with:
+
+```bash
+PI_BAR_TLDR_MODEL=anthropic/claude-haiku-4-5 pi
+```
+
+You can also set `bar.tldrModel` in pi settings; `tldr.model` is accepted for compatibility with existing settings.
 
 ### Configure extension statuses
 
@@ -76,10 +95,10 @@ PI_BAR_ICONS=nerdfont pi
 
 Supported presets:
 
-- `unicode` — default, e.g. `◈ gpt-5.5  ❯  ✦ think:medium  ❯  ◷ 42.7% / 272k  ❯  ✧ plan:active`
-- `plain` — maximum compatibility, e.g. `model:gpt-5.5 | think:medium | ctx:42.7% / 272k | ext:plan:active`
-- `emoji` — colorful emoji markers, e.g. `🤖 gpt-5.5  ›  ✨ think:medium  ›  🧭 42.7% / 272k  ›  🧩 plan:active`
-- `nerdfont` — icon-font glyphs for terminals configured with a Nerd Font, e.g. `󰚩 gpt-5.5    󰧑 think:medium    󰍛 42.7% / 272k    󰐱 plan:active`
+- `unicode` — default, e.g. `◈ gpt-5.5  ❯  ✦ think:medium  ❯  ◷ 42.7% / 272k  ❯  ⓘ Reading files  ❯  ✧ plan:active`
+- `plain` — maximum compatibility, e.g. `model:gpt-5.5 | think:medium | ctx:42.7% / 272k | tldr:Reading files | ext:plan:active`
+- `emoji` — colorful emoji markers, e.g. `🤖 gpt-5.5  ›  ✨ think:medium  ›  🧭 42.7% / 272k  ›  📝 Reading files  ›  🧩 plan:active`
+- `nerdfont` — icon-font glyphs for terminals configured with a Nerd Font, e.g. `󰚩 gpt-5.5    󰧑 think:medium    󰍛 42.7% / 272k    󰦨 Reading files    󰐱 plan:active`
 
 ## Compatibility
 
@@ -97,3 +116,5 @@ PI_BAR_ICONS=plain pi
 ## Security note
 
 Pi extensions run with your local user permissions. Review any pi package source before installing it.
+
+Live TLDR generation sends short snippets from recent prompt, assistant, tool, and result activity to the selected TLDR model provider. Disable the `tldr` segment with `PI_BAR_SHOW` if that is unacceptable.

package/extensions/status-footer.ts

@@ -2,7 +2,7 @@
  * pi-bar — footer/statusline extension.
  *
  * Replaces the built-in footer with left-aligned segments:
- *   ◈ <model name> ❯ ✦ think:<level> ❯ ◷ <context% / window> ❯ ✧ <extension statuses>
+ *   ◈ <model name> ❯ ✦ think:<level> ❯ ◷ <context% / window> ❯ ⓘ <tldr> ❯ ✧ <extension statuses>
  *
  * Examples:
  *   ◈ claude-opus-4.7  ❯  ✦ think:med  ❯  ◷ 2.6% / 1.0M
@@ -11,18 +11,22 @@
  * and after each assistant turn so context usage stays current.
  *
  * Configuration env vars:
- *   PI_BAR_SHOW=model,thinking,context,extensions
+ *   PI_BAR_SHOW=model,thinking,context,tldr,extensions
  *   PI_BAR_THRESHOLDS=70,90
  *   PI_BAR_ICONS=unicode|plain|emoji|nerdfont
+ *   PI_BAR_TLDR_MAX_WIDTH=64
  */
 
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { complete, type UserMessage } from "@earendil-works/pi-ai";
 import {
 	getSettingsListTheme,
+	SettingsManager,
 	type ExtensionAPI,
 	type ExtensionContext,
+	type ThemeColor,
 } from "@earendil-works/pi-coding-agent";
 import {
 	Container,
@@ -31,7 +35,7 @@ import {
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
 
-type SegmentName = "model" | "thinking" | "context" | "extensions";
+type SegmentName = "model" | "thinking" | "context" | "tldr" | "extensions";
 type IconPreset = "unicode" | "plain" | "emoji" | "nerdfont";
 type StatusFilter =
 	| { mode: "all"; hidden: Set<string> }
@@ -39,8 +43,48 @@ type StatusFilter =
 type SerializedStatusFilter =
 	| { mode: "all"; hidden: string[] }
 	| { mode: "only"; shown: string[] };
+type TldrActivityType =
+	| "user_message"
+	| "assistant_update"
+	| "tool_call"
+	| "tool_result"
+	| "assistant_final"
+	| "assistant_failure";
+type TldrDisplayPriority = "immediate" | "normal" | "final";
+type TldrActivity = {
+	index: number;
+	activityType: TldrActivityType;
+	displayPriority: TldrDisplayPriority;
+	text: string;
+};
+type TldrCheckpoint = {
+	activityIndex: number;
+	displayPriority: TldrDisplayPriority;
+	text: string;
+};
+type TldrCheckpointJob = {
+	activityIndex: number;
+	displayPriority: TldrDisplayPriority;
+	runId: number;
+};
+type TldrModelPreference = { provider: string; id: string };
+type FastModelAuth = {
+	model: Parameters<typeof complete>[0];
+	apiKey: string;
+	headers?: Record<string, string>;
+};
 
 const STATUS_FILTER_ENTRY_TYPE = "pi-bar-status-filter";
+const DEFAULT_TLDR_MAX_WIDTH = 64;
+const SETTINGS_TLDR_KEY = "tldr";
+const SETTINGS_BAR_KEY = "bar";
+const MAX_ACTIVITY_TEXT_CHARS = 1_500;
+const MAX_RETAINED_RAW_ACTIVITIES = 128;
+const MAX_CONTEXT_CHECKPOINTS = 8;
+const TLDR_MAX_TOKENS = 120;
+const TLDR_REQUEST_TIMEOUT_MS = 2_000;
+const TLDR_DISPLAY_UPDATE_INTERVAL_MS = 1_200;
+const TLDR_TARGET_SUMMARY_CHARS = 80;
 const CONFIG_PATH =
 	process.env.PI_BAR_CONFIG ?? join(homedir(), ".pi", "agent", "pi-bar.json");
 
@@ -48,6 +92,7 @@ const DEFAULT_SEGMENTS: SegmentName[] = [
 	"model",
 	"thinking",
 	"context",
+	"tldr",
 	"extensions",
 ];
 const DEFAULT_WARNING_THRESHOLD = 70;
@@ -59,6 +104,7 @@ const ICON_PRESETS: Record<
 		model: string;
 		thinking: string;
 		context: string;
+		tldr: string;
 		extensions: string;
 		separator: string;
 	}
@@ -67,6 +113,7 @@ const ICON_PRESETS: Record<
 		model: "◈",
 		thinking: "✦",
 		context: "◷",
+		tldr: "ⓘ",
 		extensions: "✧",
 		separator: "❯",
 	},
@@ -74,6 +121,7 @@ const ICON_PRESETS: Record<
 		model: "model",
 		thinking: "think",
 		context: "ctx",
+		tldr: "tldr",
 		extensions: "ext",
 		separator: "|",
 	},
@@ -81,6 +129,7 @@ const ICON_PRESETS: Record<
 		model: "🤖",
 		thinking: "✨",
 		context: "🧭",
+		tldr: "📝",
 		extensions: "🧩",
 		separator: "›",
 	},
@@ -88,6 +137,7 @@ const ICON_PRESETS: Record<
 		model: "󰚩",
 		thinking: "󰧑",
 		context: "󰍛",
+		tldr: "󰦨",
 		extensions: "󰐱",
 		separator: "",
 	},
@@ -111,7 +161,7 @@ function formatModelName(id: string | undefined): string {
 	return base.replace(/-\d{8}$/, "").replace(/-\d{4}-\d{2}-\d{2}$/, "");
 }
 
-function thinkingColor(level: string): string {
+function thinkingColor(level: string): ThemeColor {
 	switch (level) {
 		case "off":
 			return "thinkingOff";
@@ -137,7 +187,7 @@ function contextColor(
 	percent: number | null | undefined,
 	warningThreshold: number,
 	errorThreshold: number,
-): string {
+): ThemeColor {
 	if (percent === null || percent === undefined) return "muted";
 	if (percent >= errorThreshold) return "error";
 	if (percent >= warningThreshold) return "warning";
@@ -152,7 +202,7 @@ function parseSegments(): SegmentName[] {
 		.split(",")
 		.map((segment) => segment.trim().toLowerCase())
 		.filter((segment): segment is SegmentName =>
-			["model", "thinking", "context", "extensions"].includes(segment),
+			["model", "thinking", "context", "tldr", "extensions"].includes(segment),
 		);
 
 	return requested.length > 0 ? requested : DEFAULT_SEGMENTS;
@@ -192,11 +242,543 @@ function parseIconPreset(): IconPreset {
 	return "unicode";
 }
 
+function parseTldrMaxWidth(): number {
+	const raw = process.env.PI_BAR_TLDR_MAX_WIDTH;
+	if (!raw) return DEFAULT_TLDR_MAX_WIDTH;
+
+	const value = Number.parseInt(raw, 10);
+	if (Number.isFinite(value) && value >= 10 && value <= 500) return value;
+	return DEFAULT_TLDR_MAX_WIDTH;
+}
+
+function parseTldrModelSpec(value: string): TldrModelPreference | undefined {
+	const trimmed = value.trim();
+	if (!trimmed || trimmed === "auto") return undefined;
+	const separator = trimmed.indexOf("/");
+	if (separator <= 0 || separator === trimmed.length - 1) return undefined;
+	return { provider: trimmed.slice(0, separator), id: trimmed.slice(separator + 1) };
+}
+
+function settingsModelValue(settings: Record<string, unknown>): string | undefined {
+	const bar = settings[SETTINGS_BAR_KEY];
+	if (bar && typeof bar === "object" && !Array.isArray(bar)) {
+		const value = (bar as Record<string, unknown>).tldrModel;
+		if (typeof value === "string") return value;
+	}
+
+	const tldr = settings[SETTINGS_TLDR_KEY];
+	if (tldr && typeof tldr === "object" && !Array.isArray(tldr)) {
+		const value = (tldr as Record<string, unknown>).model;
+		if (typeof value === "string") return value;
+	}
+
+	return undefined;
+}
+
+function resolveTldrModelPreference(cwd: string): TldrModelPreference | undefined {
+	const envModel = process.env.PI_BAR_TLDR_MODEL;
+	if (envModel) return parseTldrModelSpec(envModel);
+
+	const settings = SettingsManager.create(cwd);
+	const projectModel = settingsModelValue(
+		settings.getProjectSettings() as Record<string, unknown>,
+	);
+	if (projectModel !== undefined) return parseTldrModelSpec(projectModel);
+
+	const globalModel = settingsModelValue(
+		settings.getGlobalSettings() as Record<string, unknown>,
+	);
+	return globalModel ? parseTldrModelSpec(globalModel) : undefined;
+}
+
+const FAST_TLDR_MODELS: readonly TldrModelPreference[] = [
+	{ provider: "anthropic", id: "claude-haiku-4-5" },
+	{ provider: "anthropic", id: "claude-haiku-4-5-20251001" },
+	{ provider: "openai-codex", id: "gpt-5.4-mini" },
+	{ provider: "openai-codex", id: "gpt-5.3-codex-spark" },
+];
+
+function formatTldrModelKey(model: TldrModelPreference): string {
+	return `${model.provider}/${model.id}`;
+}
+
+async function getModelAuth(
+	ctx: ExtensionContext,
+	preference: TldrModelPreference,
+): Promise<FastModelAuth | undefined> {
+	const model = ctx.modelRegistry.find(preference.provider, preference.id);
+	if (!model) return undefined;
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	return auth.ok && auth.apiKey
+		? { model, apiKey: auth.apiKey, headers: auth.headers }
+		: undefined;
+}
+
+async function getFastTldrModelAuth(
+	ctx: ExtensionContext,
+	configuredModel?: TldrModelPreference,
+): Promise<FastModelAuth | undefined> {
+	if (configuredModel) {
+		const configuredAuth = await getModelAuth(ctx, configuredModel);
+		if (configuredAuth) return configuredAuth;
+	}
+
+	for (const candidate of FAST_TLDR_MODELS) {
+		if (configuredModel && formatTldrModelKey(candidate) === formatTldrModelKey(configuredModel)) {
+			continue;
+		}
+		const auth = await getModelAuth(ctx, candidate);
+		if (auth) return auth;
+	}
+
+	return undefined;
+}
+
+function truncateText(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars - 1)}…`;
+}
+
+function extractTextContent(content: readonly unknown[] | undefined): string | undefined {
+	if (!content) return undefined;
+	const text = content
+		.map((part) => {
+			if (!part || typeof part !== "object") return undefined;
+			const record = part as Record<string, unknown>;
+			return record.type === "text" && typeof record.text === "string"
+				? record.text
+				: undefined;
+		})
+		.filter((part): part is string => Boolean(part))
+		.join("\n");
+	return text.length > 0 ? text : undefined;
+}
+
 function prefixed(icon: string, text: string, preset: IconPreset): string {
 	if (preset === "plain") return `${icon}:${text}`;
 	return `${icon} ${text}`;
 }
 
+class TldrFactCollector {
+	private nextIndex = 1;
+	private readonly activities: TldrActivity[] = [];
+
+	resetConversation(): void {
+		this.nextIndex = 1;
+		this.activities.splice(0);
+	}
+
+	recordUserMessage(prompt: string): TldrActivity {
+		return this.addActivity("user_message", "immediate", `User message: ${prompt}`);
+	}
+
+	recordAssistantUpdate(message: unknown): TldrActivity | undefined {
+		if (!message || typeof message !== "object") return undefined;
+		const record = message as Record<string, unknown>;
+		if (record.role !== "assistant") return undefined;
+		const text = extractTextContent(record.content as readonly unknown[] | undefined);
+		return text
+			? this.addActivity("assistant_update", "normal", `Assistant update: ${text}`)
+			: undefined;
+	}
+
+	recordToolCall(event: { toolName: string }): TldrActivity {
+		return this.addActivity("tool_call", "normal", `Tool started: ${event.toolName}`);
+	}
+
+	recordToolResult(event: {
+		toolName: string;
+		isError?: boolean;
+		content?: readonly unknown[];
+	}): TldrActivity {
+		const resultText = extractTextContent(event.content);
+		const status = event.isError ? "error" : "ok";
+		return this.addActivity(
+			"tool_result",
+			"normal",
+			resultText
+				? `Tool finished: ${event.toolName} (${status})\n${resultText}`
+				: `Tool finished: ${event.toolName} (${status})`,
+		);
+	}
+
+	recordMessageEnd(message: unknown): TldrActivity | "emptyFinalStop" | "ignored" {
+		if (!message || typeof message !== "object") return "ignored";
+		const record = message as Record<string, unknown>;
+		if (record.role !== "assistant") return "ignored";
+
+		const stopReason = typeof record.stopReason === "string" ? record.stopReason : undefined;
+		if (stopReason === "toolUse") return "ignored";
+
+		let text: string | undefined;
+		if (stopReason === "stop") {
+			const finalText = extractTextContent(record.content as readonly unknown[] | undefined);
+			if (!finalText) return "emptyFinalStop";
+			text = `Assistant final response: ${finalText}`;
+		} else if (stopReason) {
+			const error = typeof record.errorMessage === "string" ? record.errorMessage : undefined;
+			text = error
+				? `Assistant finished with ${stopReason}: ${error}`
+				: `Assistant finished with ${stopReason}`;
+		}
+
+		return text
+			? this.addActivity(
+					stopReason === "stop" ? "assistant_final" : "assistant_failure",
+					"final",
+					text,
+				)
+			: "ignored";
+	}
+
+	activitiesAfter(previousIndex: number, throughIndex: number): readonly TldrActivity[] {
+		return this.activities.filter(
+			(activity) => activity.index > previousIndex && activity.index <= throughIndex,
+		);
+	}
+
+	latestActivityIndex(): number {
+		return this.nextIndex - 1;
+	}
+
+	discardActivitiesThrough(activityIndex: number): void {
+		const firstRetainedIndex = this.activities.findIndex(
+			(activity) => activity.index > activityIndex,
+		);
+		if (firstRetainedIndex === -1) {
+			this.activities.splice(0);
+			return;
+		}
+		if (firstRetainedIndex > 0) this.activities.splice(0, firstRetainedIndex);
+	}
+
+	private addActivity(
+		activityType: TldrActivityType,
+		displayPriority: TldrDisplayPriority,
+		text: string,
+	): TldrActivity {
+		const activity = {
+			index: this.nextIndex,
+			activityType,
+			displayPriority,
+			text: truncateText(text, MAX_ACTIVITY_TEXT_CHARS),
+		};
+		this.nextIndex++;
+		this.activities.push(activity);
+		if (this.activities.length > MAX_RETAINED_RAW_ACTIVITIES) {
+			this.activities.splice(0, this.activities.length - MAX_RETAINED_RAW_ACTIVITIES);
+		}
+		return activity;
+	}
+}
+
+class FooterTldrEngine {
+	private readonly facts = new TldrFactCollector();
+	private configuredModel?: TldrModelPreference;
+	private runId = 0;
+	private latestAcceptedActivityIndex = 0;
+	private lastRenderedActivityIndex = 0;
+	private lastRenderedText = "";
+	private lastDisplayAt = Number.NEGATIVE_INFINITY;
+	private readonly acceptedCheckpoints: TldrCheckpoint[] = [];
+	private checkpointQueue: TldrCheckpointJob[] = [];
+	private inFlightCheckpoint?: TldrCheckpointJob;
+	private pendingDisplayCheckpoint?: TldrCheckpoint;
+	private displayTimer?: ReturnType<typeof setTimeout>;
+	private abortController?: AbortController;
+	private currentText: string | null = null;
+
+	constructor(private readonly requestRender: () => void) {}
+
+	text(maxWidth: number): string | null {
+		return this.currentText ? truncateToWidth(this.currentText, maxWidth) : null;
+	}
+
+	startSession(cwd: string): void {
+		this.configuredModel = resolveTldrModelPreference(cwd);
+		this.facts.resetConversation();
+		this.startFreshRun();
+	}
+
+	shutdown(): void {
+		this.facts.resetConversation();
+		this.startFreshRun();
+	}
+
+	recordUserMessage(ctx: ExtensionContext, prompt: string): void {
+		this.currentText = null;
+		this.requestRender();
+		this.enqueue(ctx, this.facts.recordUserMessage(prompt));
+	}
+
+	recordAssistantUpdate(ctx: ExtensionContext, message: unknown): void {
+		const activity = this.facts.recordAssistantUpdate(message);
+		if (activity) this.enqueue(ctx, activity);
+	}
+
+	recordToolCall(ctx: ExtensionContext, event: { toolName: string }): void {
+		this.enqueue(ctx, this.facts.recordToolCall(event));
+	}
+
+	recordToolResult(
+		ctx: ExtensionContext,
+		event: { toolName: string; isError?: boolean; content?: readonly unknown[] },
+	): void {
+		this.enqueue(ctx, this.facts.recordToolResult(event));
+	}
+
+	recordMessageEnd(ctx: ExtensionContext, message: unknown): void {
+		const result = this.facts.recordMessageEnd(message);
+		if (result === "ignored") return;
+		if (result === "emptyFinalStop") {
+			this.facts.resetConversation();
+			this.startFreshRun();
+			return;
+		}
+		this.enqueue(ctx, result);
+	}
+
+	private startFreshRun(): void {
+		this.runId++;
+		this.cancelWork();
+		this.latestAcceptedActivityIndex = 0;
+		this.lastRenderedActivityIndex = 0;
+		this.lastRenderedText = "";
+		this.lastDisplayAt = Number.NEGATIVE_INFINITY;
+		this.acceptedCheckpoints.splice(0);
+		this.pendingDisplayCheckpoint = undefined;
+		this.currentText = null;
+		this.requestRender();
+	}
+
+	private cancelWork(): void {
+		if (this.displayTimer) clearTimeout(this.displayTimer);
+		this.displayTimer = undefined;
+		this.checkpointQueue.splice(0);
+		this.inFlightCheckpoint = undefined;
+		this.abortController?.abort();
+		this.abortController = undefined;
+	}
+
+	private enqueue(ctx: ExtensionContext, activity: TldrActivity): void {
+		if (!ctx.hasUI) return;
+		const job = {
+			activityIndex: activity.index,
+			displayPriority: activity.displayPriority,
+			runId: this.runId,
+		};
+
+		if (job.displayPriority === "immediate") {
+			this.clearPendingDisplay();
+			this.lastRenderedText = "";
+			this.checkpointQueue.splice(0);
+			this.abortInFlightCheckpoint();
+			this.checkpointQueue.push(job);
+		} else if (job.displayPriority === "final") {
+			this.clearPendingDisplay();
+			this.checkpointQueue = this.checkpointQueue.filter(
+				(queued) => queued.displayPriority !== "normal",
+			);
+			if (this.inFlightCheckpoint?.displayPriority === "normal") {
+				this.abortInFlightCheckpoint();
+			}
+			this.checkpointQueue.push(job);
+		} else {
+			this.checkpointQueue = this.checkpointQueue.filter(
+				(queued) => queued.displayPriority !== "normal",
+			);
+			this.checkpointQueue.push(job);
+		}
+
+		this.pump(ctx);
+	}
+
+	private clearPendingDisplay(): void {
+		if (this.displayTimer) clearTimeout(this.displayTimer);
+		this.displayTimer = undefined;
+		this.pendingDisplayCheckpoint = undefined;
+	}
+
+	private abortInFlightCheckpoint(): void {
+		if (!this.inFlightCheckpoint) return;
+		this.abortController?.abort();
+		this.abortController = undefined;
+		this.inFlightCheckpoint = undefined;
+	}
+
+	private pump(ctx: ExtensionContext): void {
+		if (!ctx.hasUI || this.inFlightCheckpoint) return;
+		const job = this.checkpointQueue.shift();
+		if (!job) return;
+		if (job.runId !== this.runId || job.activityIndex <= this.latestAcceptedActivityIndex) {
+			this.pump(ctx);
+			return;
+		}
+		this.inFlightCheckpoint = job;
+		void this.runCheckpointRequest(ctx, job);
+	}
+
+	private isCurrentJob(job: TldrCheckpointJob): boolean {
+		return job.runId === this.runId && this.inFlightCheckpoint === job;
+	}
+
+	private async runCheckpointRequest(
+		ctx: ExtensionContext,
+		job: TldrCheckpointJob,
+	): Promise<void> {
+		let abortController: AbortController | undefined;
+		try {
+			const prompt = this.checkpointPrompt(job);
+			if (!prompt) return;
+			const auth = await getFastTldrModelAuth(ctx, this.configuredModel);
+			if (!this.isCurrentJob(job) || !auth) return;
+
+			abortController = new AbortController();
+			this.abortController = abortController;
+			const response = await complete(
+				auth.model,
+				{ systemPrompt: checkpointSystemPrompt(job), messages: [prompt] },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					maxTokens: TLDR_MAX_TOKENS,
+					maxRetries: 0,
+					cacheRetention: "none",
+					timeoutMs: TLDR_REQUEST_TIMEOUT_MS,
+					signal: abortController.signal,
+				},
+			);
+			if (!this.isCurrentJob(job) || response.stopReason !== "stop") return;
+
+			const text = extractTextContent(response.content) ?? "";
+			if (!text) return;
+			const checkpoint = {
+				activityIndex: job.activityIndex,
+				displayPriority: job.displayPriority,
+				text,
+			};
+			this.acceptCheckpoint(checkpoint);
+			this.considerDisplayingCheckpoint(ctx, checkpoint);
+		} catch {
+			// Best effort. Later checkpoints include unaccepted raw activity.
+		} finally {
+			if (abortController && this.abortController === abortController) {
+				this.abortController = undefined;
+			}
+			if (this.inFlightCheckpoint === job) this.inFlightCheckpoint = undefined;
+			this.pump(ctx);
+		}
+	}
+
+	private acceptCheckpoint(checkpoint: TldrCheckpoint): void {
+		this.acceptedCheckpoints.push(checkpoint);
+		if (this.acceptedCheckpoints.length > MAX_CONTEXT_CHECKPOINTS) {
+			this.acceptedCheckpoints.splice(
+				0,
+				this.acceptedCheckpoints.length - MAX_CONTEXT_CHECKPOINTS,
+			);
+		}
+		this.latestAcceptedActivityIndex = checkpoint.activityIndex;
+		this.facts.discardActivitiesThrough(checkpoint.activityIndex);
+	}
+
+	private considerDisplayingCheckpoint(
+		ctx: ExtensionContext,
+		checkpoint: TldrCheckpoint,
+	): void {
+		if (checkpoint.activityIndex <= this.lastRenderedActivityIndex) return;
+		if (checkpoint.activityIndex !== this.facts.latestActivityIndex()) return;
+
+		if (checkpoint.displayPriority !== "normal" || !this.lastRenderedText) {
+			this.clearPendingDisplay();
+			this.renderCheckpoint(checkpoint);
+			return;
+		}
+
+		const elapsedMs = performance.now() - this.lastDisplayAt;
+		if (elapsedMs >= TLDR_DISPLAY_UPDATE_INTERVAL_MS) {
+			this.clearPendingDisplay();
+			this.renderCheckpoint(checkpoint);
+			return;
+		}
+
+		this.pendingDisplayCheckpoint = checkpoint;
+		if (this.displayTimer) return;
+		this.displayTimer = setTimeout(() => {
+			this.displayTimer = undefined;
+			const pending = this.pendingDisplayCheckpoint;
+			this.pendingDisplayCheckpoint = undefined;
+			if (!pending || pending.activityIndex !== this.facts.latestActivityIndex()) return;
+			this.renderCheckpoint(pending);
+		}, TLDR_DISPLAY_UPDATE_INTERVAL_MS - elapsedMs);
+	}
+
+	private renderCheckpoint(checkpoint: TldrCheckpoint): void {
+		if (checkpoint.activityIndex <= this.lastRenderedActivityIndex) return;
+		if (checkpoint.text === this.lastRenderedText) return;
+		this.lastRenderedActivityIndex = checkpoint.activityIndex;
+		this.lastRenderedText = checkpoint.text;
+		this.lastDisplayAt = performance.now();
+		this.currentText = checkpoint.text;
+		this.requestRender();
+	}
+
+	private checkpointPrompt(job: TldrCheckpointJob): UserMessage | undefined {
+		const rawActivities = this.facts.activitiesAfter(
+			this.latestAcceptedActivityIndex,
+			job.activityIndex,
+		);
+		if (rawActivities.length === 0) return undefined;
+		return {
+			role: "user",
+			content: [
+				{
+					type: "text",
+					text: [
+						"Previous generated TLDR checkpoints:",
+						previousCheckpointLines(this.acceptedCheckpoints),
+						"",
+						"New raw activity since the latest accepted checkpoint:",
+						...rawActivities.map(formatRawActivity),
+						"",
+						`Write the next TLDR through activity ${job.activityIndex}.`,
+					].join("\n"),
+				},
+			],
+			timestamp: Date.now(),
+		};
+	}
+}
+
+function checkpointSystemPrompt(job: TldrCheckpointJob): string {
+	const tenseInstruction =
+		job.displayPriority === "final"
+			? "Start with a past-tense verb."
+			: "Start with a present-tense -ing verb.";
+	return `Write one plain-English TLDR for a terminal coding agent.
+Use the prior TLDRs for context and the new activity for the update.
+Summarize only activity up to the requested index.
+If context is sparse, still summarize the available activity.
+Never ask for more information or say there is not enough context.
+Return exactly one complete sentence under ${TLDR_TARGET_SUMMARY_CHARS} characters.
+Use third person. Do not address the user.
+Plain text only; no markdown, JSON, code, bullets, quotes, or file/tool names.
+${tenseInstruction}`;
+}
+
+function previousCheckpointLines(checkpoints: readonly TldrCheckpoint[]): string {
+	if (checkpoints.length === 0) return "none";
+	return checkpoints
+		.slice(-MAX_CONTEXT_CHECKPOINTS)
+		.map((checkpoint) => `- Through activity ${checkpoint.activityIndex}: ${checkpoint.text}`)
+		.join("\n");
+}
+
+function formatRawActivity(activity: TldrActivity): string {
+	return `[${activity.index}] ${activity.activityType}: ${activity.text}`;
+}
+
 function shouldShowStatus(key: string, filter: StatusFilter): boolean {
 	if (filter.mode === "only") return filter.shown.has(key);
 	return !filter.hidden.has(key);
@@ -293,6 +875,7 @@ export default function (pi: ExtensionAPI) {
 	let statusFilter: StatusFilter = { mode: "all", hidden: new Set() };
 	const seenStatusKeys = new Set<string>();
 	const refresh = () => requestRender?.();
+	const tldr = new FooterTldrEngine(refresh);
 	const restoreStatusFilter = (ctx: ExtensionContext) => {
 		let restoredFilter = readGlobalStatusFilter();
 		if (!restoredFilter) {
@@ -479,13 +1062,29 @@ export default function (pi: ExtensionAPI) {
 	pi.on("model_select", async () => refresh());
 	pi.on("thinking_level_select", async () => refresh());
 	pi.on("turn_end", async () => refresh());
-	pi.on("message_end", async () => refresh());
+	pi.on("before_agent_start", async (event, ctx) => {
+		tldr.recordUserMessage(ctx, event.prompt);
+	});
+	pi.on("message_update", async (event, ctx) => {
+		tldr.recordAssistantUpdate(ctx, event.message);
+	});
+	pi.on("tool_call", async (event, ctx) => {
+		tldr.recordToolCall(ctx, event);
+	});
+	pi.on("tool_result", async (event, ctx) => {
+		tldr.recordToolResult(ctx, event);
+	});
+	pi.on("message_end", async (event, ctx) => {
+		tldr.recordMessageEnd(ctx, event.message);
+		refresh();
+	});
 	pi.on("session_tree", async (_event, ctx) => {
 		restoreStatusFilter(ctx);
 		refresh();
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		tldr.startSession(ctx.cwd);
 		restoreStatusFilter(ctx);
 
 		if (!ctx.hasUI) return;
@@ -494,6 +1093,7 @@ export default function (pi: ExtensionAPI) {
 		const iconPreset = parseIconPreset();
 		const icons = ICON_PRESETS[iconPreset];
 		const { warningThreshold, errorThreshold } = parseThresholds();
+		const tldrMaxWidth = parseTldrMaxWidth();
 
 		ctx.ui.setFooter((tui, theme, footerData) => {
 			requestRender = () => tui.requestRender();
@@ -521,6 +1121,7 @@ export default function (pi: ExtensionAPI) {
 					const contextText = usage
 						? `${usage.percent !== null ? `${usage.percent.toFixed(1)}%` : "—%"} / ${formatTokens(usage.contextWindow)}`
 						: "—";
+					const tldrText = tldr.text(tldrMaxWidth);
 
 					const segmentRenderers: Record<SegmentName, string | null> = {
 						model: theme.fg(
@@ -535,6 +1136,9 @@ export default function (pi: ExtensionAPI) {
 							contextSegmentColor,
 							prefixed(icons.context, contextText, iconPreset),
 						),
+						tldr: tldrText
+							? theme.fg("muted", prefixed(icons.tldr, tldrText, iconPreset))
+							: null,
 						extensions: extensionStatuses
 							? theme.fg(
 									"muted",
@@ -556,6 +1160,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
+		tldr.shutdown();
 		if (ctx.hasUI) ctx.ui.setFooter(undefined);
 	});
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-bar",
-  "version": "0.3.5",
-  "description": "Never accidentally run Opus on a typo. Pi footer/statusline showing active model, thinking level, context usage, and extension statuses.",
+  "version": "0.3.7",
+  "description": "Never accidentally run Opus on a typo. Pi footer/statusline showing active model, thinking level, context usage, live TLDR, and extension statuses.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -13,7 +13,8 @@
     "model",
     "thinking",
     "context",
-    "context-window"
+    "context-window",
+    "tldr"
   ],
   "license": "MIT",
   "repository": {
@@ -31,10 +32,14 @@
     "LICENSE"
   ],
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
@@ -46,6 +51,6 @@
     "extensions": [
       "./extensions/status-footer.ts"
     ],
-    "image": "https://cdn.jsdelivr.net/npm/pi-bar@0.3.5/assets/screenshot.png"
+    "image": "https://cdn.jsdelivr.net/npm/pi-bar@0.3.7/assets/screenshot.png"
   }
 }