@shanepadgett/tau-agent 0.5.0 → 0.6.0

package/extensions/explore/autoread.ts

@@ -1,9 +1,11 @@
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { resolve } from "node:path";
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import { onTauEvent, type TauAgentEvents } from "../../shared/events.js";
 import type { ToolRowStateStore } from "../../shared/tool-row-state.js";
 import { Marker, type MarkerState } from "@shanepadgett/tau-tui";
+import type { ReadCacheMetaV1 } from "./read-cache.ts";
 
 const AUTOREAD_MESSAGE_TYPE = "tau.autoread";
 
@@ -17,6 +19,7 @@ interface AutoreadDetails {
 	batchId: string;
 	status: AutoreadStatus;
 	error?: string;
+	readCache?: ReadCacheMetaV1;
 }
 
 export function registerAutoread(pi: ExtensionAPI, rowState: ToolRowStateStore): void {
@@ -34,12 +37,26 @@ export function registerAutoread(pi: ExtensionAPI, rowState: ToolRowStateStore):
 					batchId: event.batchId,
 				} satisfies Omit<AutoreadDetails, "status" | "error">;
 				try {
-					const content = await readFile(join(event.cwd, file.path), "utf8");
+					const pathKey = resolve(event.cwd, file.path);
+					const bytes = await readFile(pathKey);
+					const content = bytes.toString("utf8");
+					const totalLines = content.split("\n").length;
+					const readCache = {
+						v: 1,
+						pathKey,
+						scopeKey: "full:n0",
+						servedHash: createHash("sha256").update(bytes).digest("hex"),
+						mode: "baseline",
+						baselineTokens: Math.ceil(content.length / 4),
+						returnedTokens: Math.ceil(content.length / 4),
+						totalLines,
+						summary: `${totalLines} lines`,
+					} satisfies ReadCacheMetaV1;
 					pi.sendMessage({
 						customType: AUTOREAD_MESSAGE_TYPE,
 						content: `${file.path}\n${content}`,
 						display: true,
-						details: { ...details, status: "read" },
+						details: { ...details, status: "read", readCache },
 					});
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);

package/extensions/explore/index.ts

@@ -4,14 +4,35 @@ import { registerAutoread } from "./autoread.ts";
 import { createFindTool } from "./find.ts";
 import { createGrepTool } from "./grep.ts";
 import { createLsTool } from "./ls.ts";
+import { createReadCacheStore } from "./read-cache.ts";
+import { createReadSnapshotStore } from "./read-snapshots.ts";
+import { showReadStats } from "./read-stats.ts";
 import { createExploreReadTool } from "./read.ts";
 
 export default function exploreExtension(pi: ExtensionAPI): void {
 	const rowState = createToolRowStateStore(pi, "explore.tool-row-state");
+	const readCache = createReadCacheStore();
+	const readSnapshots = createReadSnapshotStore();
 	registerAutoread(pi, rowState);
 	pi.registerTool(createLsTool(rowState));
 	pi.registerTool(createFindTool(rowState));
 	pi.registerTool(createGrepTool(rowState));
-	pi.registerTool(createExploreReadTool(rowState));
-	pi.on("session_start", () => rowState.clear());
+	pi.registerTool(createExploreReadTool(rowState, readCache, readSnapshots));
+	pi.registerCommand("read-stats", {
+		description: "Show estimated read token and cost savings for this session",
+		async handler(_args, ctx) {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("Read stats require TUI mode", "error");
+				return;
+			}
+			await showReadStats(ctx);
+		},
+	});
+	pi.on("session_start", () => {
+		rowState.clear();
+		readCache.clear();
+		readSnapshots.clear();
+	});
+	pi.on("session_compact", () => readCache.clear());
+	pi.on("session_tree", () => readCache.clear());
 }

package/extensions/explore/read-cache.ts

@@ -0,0 +1,209 @@
+import { resolve } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type ReadCacheMode = "baseline" | "recovery" | "unchanged" | "diff";
+
+export interface ReadCacheMetaV1 {
+	v: 1;
+	pathKey: string;
+	scopeKey: string;
+	servedHash: string;
+	baseHash?: string;
+	mode: ReadCacheMode;
+	baselineTokens: number;
+	returnedTokens: number;
+	totalLines: number;
+	summary: string;
+}
+
+interface ScopeTrust {
+	hash: string;
+	sequence: number;
+}
+
+interface ReplayState {
+	trust: Map<string, Map<string, ScopeTrust>>;
+	unlockedPaths: Set<string>;
+	sequence: number;
+}
+
+interface OverlayState {
+	trust: Map<string, Map<string, ScopeTrust>>;
+	sequence: number;
+}
+
+export interface ReadCacheDecision {
+	baseHash?: string;
+	recovery: boolean;
+}
+
+export interface ReadCacheStore {
+	decision(ctx: ExtensionContext, pathKey: string, scopeKey: string): ReadCacheDecision;
+	record(ctx: ExtensionContext, meta: ReadCacheMetaV1): void;
+	clear(): void;
+}
+
+export function createReadCacheStore(): ReadCacheStore {
+	const overlays = new Map<string, OverlayState>();
+
+	return {
+		decision(ctx, pathKey, scopeKey) {
+			const state = replay(ctx);
+			const overlay = overlays.get(overlayKey(ctx));
+			if (overlay) mergeTrust(state, overlay.trust);
+			return {
+				baseHash: state.trust.get(pathKey)?.get(scopeKey)?.hash,
+				recovery: state.unlockedPaths.has(pathKey),
+			};
+		},
+		record(ctx, meta) {
+			const key = overlayKey(ctx);
+			let overlay = overlays.get(key);
+			if (!overlay) {
+				overlay = { trust: new Map(), sequence: 1_000_000_000 };
+				overlays.set(key, overlay);
+			}
+			overlay.sequence += 1;
+			setTrust(overlay.trust, meta.pathKey, meta.scopeKey, meta.servedHash, overlay.sequence);
+			while (overlays.size > 32) {
+				const oldest = overlays.keys().next().value as string | undefined;
+				if (oldest === undefined) break;
+				overlays.delete(oldest);
+			}
+		},
+		clear() {
+			overlays.clear();
+		},
+	};
+}
+
+function parseReadCacheMeta(value: unknown): ReadCacheMetaV1 | undefined {
+	if (!isRecord(value) || value.v !== 1) return undefined;
+	if (typeof value.pathKey !== "string" || typeof value.scopeKey !== "string") return undefined;
+	if (typeof value.servedHash !== "string" || value.servedHash.length === 0) return undefined;
+	if (!isReadCacheMode(value.mode)) return undefined;
+	if (!isNonNegativeFinite(value.baselineTokens) || !isNonNegativeFinite(value.returnedTokens)) return undefined;
+	if (!isNonNegativeFinite(value.totalLines) || typeof value.summary !== "string") return undefined;
+	if (value.baseHash !== undefined && typeof value.baseHash !== "string") return undefined;
+	if ((value.mode === "unchanged" || value.mode === "diff") && !value.baseHash) return undefined;
+	return {
+		v: 1,
+		pathKey: value.pathKey,
+		scopeKey: value.scopeKey,
+		servedHash: value.servedHash,
+		baseHash: value.baseHash,
+		mode: value.mode,
+		baselineTokens: value.baselineTokens,
+		returnedTokens: value.returnedTokens,
+		totalLines: value.totalLines,
+		summary: value.summary,
+	};
+}
+
+export function readMetaFromMessage(message: unknown): ReadCacheMetaV1 | undefined {
+	if (!isRecord(message)) return undefined;
+	const isReadResult = message.role === "toolResult" && message.toolName === "read";
+	const isAutoread = message.customType === "tau.autoread";
+	if (!isReadResult && !isAutoread) return undefined;
+	if (!isRecord(message.details)) return undefined;
+	if (isAutoread && message.details.status !== "read") return undefined;
+	return parseReadCacheMeta(message.details.readCache);
+}
+
+function replay(ctx: ExtensionContext): ReplayState {
+	const state: ReplayState = { trust: new Map(), unlockedPaths: new Set(), sequence: 0 };
+	const manager = ctx.sessionManager;
+	if (!manager) return state;
+	const branch = manager.getBranch();
+	let start = 0;
+	for (let index = 0; index < branch.length; index += 1) {
+		const entry = branch[index];
+		if (isRecord(entry) && entry.type === "compaction") start = index + 1;
+	}
+
+	for (const entry of branch.slice(start)) {
+		if (!isRecord(entry) || entry.type !== "message" || !("message" in entry)) continue;
+		const message = entry.message;
+		const meta = readMetaFromMessage(message);
+		if (meta) {
+			state.sequence += 1;
+			applyReadMeta(state, meta);
+			continue;
+		}
+		for (const path of failedPatchPaths(message, ctx.cwd)) state.unlockedPaths.add(path);
+	}
+	return state;
+}
+
+function applyReadMeta(state: ReplayState, meta: ReadCacheMetaV1): void {
+	const existing = state.trust.get(meta.pathKey)?.get(meta.scopeKey);
+	if (meta.mode === "baseline" || meta.mode === "recovery") {
+		setTrust(state.trust, meta.pathKey, meta.scopeKey, meta.servedHash, state.sequence);
+		state.unlockedPaths.delete(meta.pathKey);
+		return;
+	}
+	if (!meta.baseHash || existing?.hash !== meta.baseHash) return;
+	if (meta.mode === "unchanged" && meta.servedHash !== meta.baseHash) return;
+	setTrust(state.trust, meta.pathKey, meta.scopeKey, meta.servedHash, state.sequence);
+}
+
+function failedPatchPaths(message: unknown, cwd: string): string[] {
+	if (!isRecord(message) || message.role !== "toolResult" || message.toolName !== "patch") return [];
+	if (
+		!isRecord(message.details) ||
+		message.details.status === "completed" ||
+		!Array.isArray(message.details.failures)
+	) {
+		return [];
+	}
+	const paths: string[] = [];
+	for (const failure of message.details.failures) {
+		if (!isRecord(failure) || typeof failure.path !== "string" || failure.path.trim().length === 0) continue;
+		paths.push(resolve(cwd, failure.path));
+	}
+	return paths;
+}
+
+function setTrust(
+	trust: Map<string, Map<string, ScopeTrust>>,
+	pathKey: string,
+	scopeKey: string,
+	hash: string,
+	sequence: number,
+): void {
+	let scopes = trust.get(pathKey);
+	if (!scopes) {
+		scopes = new Map();
+		trust.set(pathKey, scopes);
+	}
+	scopes.set(scopeKey, { hash, sequence });
+}
+
+function mergeTrust(state: ReplayState, overlay: Map<string, Map<string, ScopeTrust>>): void {
+	for (const [pathKey, scopes] of overlay) {
+		for (const [scopeKey, candidate] of scopes) {
+			const current = state.trust.get(pathKey)?.get(scopeKey);
+			if (!current || candidate.sequence > current.sequence) {
+				setTrust(state.trust, pathKey, scopeKey, candidate.hash, candidate.sequence);
+			}
+		}
+	}
+}
+
+function overlayKey(ctx: ExtensionContext): string {
+	const manager = ctx.sessionManager;
+	if (!manager) return `test:${ctx.cwd}`;
+	return `${manager.getSessionId()}:${manager.getLeafId() ?? "root"}`;
+}
+
+function isReadCacheMode(value: unknown): value is ReadCacheMode {
+	return value === "baseline" || value === "recovery" || value === "unchanged" || value === "diff";
+}
+
+function isNonNegativeFinite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}

package/extensions/explore/read-snapshots.ts

@@ -0,0 +1,44 @@
+const MAX_SNAPSHOT_BYTES = 1024 * 1024;
+const MAX_TOTAL_BYTES = 16 * 1024 * 1024;
+
+interface Snapshot {
+	text: string;
+	bytes: number;
+}
+
+export interface ReadSnapshotStore {
+	get(hash: string): string | undefined;
+	set(hash: string, text: string, bytes: number): void;
+	clear(): void;
+}
+
+export function createReadSnapshotStore(): ReadSnapshotStore {
+	const snapshots = new Map<string, Snapshot>();
+	let totalBytes = 0;
+
+	return {
+		get(hash) {
+			const snapshot = snapshots.get(hash);
+			if (!snapshot) return undefined;
+			snapshots.delete(hash);
+			snapshots.set(hash, snapshot);
+			return snapshot.text;
+		},
+		set(hash, text, bytes) {
+			if (bytes > MAX_SNAPSHOT_BYTES || snapshots.has(hash)) return;
+			snapshots.set(hash, { text, bytes });
+			totalBytes += bytes;
+			while (totalBytes > MAX_TOTAL_BYTES) {
+				const oldestHash = snapshots.keys().next().value as string | undefined;
+				if (oldestHash === undefined) break;
+				const oldest = snapshots.get(oldestHash);
+				snapshots.delete(oldestHash);
+				totalBytes -= oldest?.bytes ?? 0;
+			}
+		},
+		clear() {
+			snapshots.clear();
+			totalBytes = 0;
+		},
+	};
+}

package/extensions/explore/read-stats-panel.ts

@@ -0,0 +1,154 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, type KeybindingsManager, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { bindingHint, Tabs, ToolPanel, type ToolPanelConfig } from "@shanepadgett/tau-tui";
+import type { ReadCacheMode } from "./read-cache.ts";
+
+export interface ReadSavingsSnapshot {
+	label: string;
+	secondary: string;
+	baselineTokens: number;
+	returnedTokens: number;
+	costSaved: number;
+	unchangedCost: number;
+	diffCost: number;
+	counts: Record<ReadCacheMode, number>;
+}
+
+export function createReadStatsPanel(
+	tui: TUI,
+	theme: Theme,
+	keybindings: KeybindingsManager,
+	done: (result: unknown) => void,
+	current: ReadSavingsSnapshot,
+	whole: ReadSavingsSnapshot,
+): Component {
+	return new ReadStatsPanel(tui, theme, keybindings, done, current, whole);
+}
+
+class ReadStatsPanel implements Component {
+	private readonly tui: TUI;
+	private readonly keybindings: KeybindingsManager;
+	private readonly done: (result: unknown) => void;
+	private readonly snapshots: readonly [ReadSavingsSnapshot, ReadSavingsSnapshot];
+	private readonly tabs: Tabs;
+	private readonly config: ToolPanelConfig;
+	private readonly panel: ToolPanel;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		keybindings: KeybindingsManager,
+		done: (result: unknown) => void,
+		current: ReadSavingsSnapshot,
+		whole: ReadSavingsSnapshot,
+	) {
+		this.tui = tui;
+		this.keybindings = keybindings;
+		this.done = done;
+		this.snapshots = [current, whole];
+		this.tabs = new Tabs(
+			theme,
+			this.snapshots.map((snapshot) => ({
+				id: snapshot.label,
+				label: snapshot.label,
+				body: new SavingsBody(theme, snapshot),
+			})),
+			current.label,
+		);
+		this.config = {
+			title: "Read savings",
+			secondary: current.secondary,
+			body: this.tabs,
+			footer: {
+				kind: "hints",
+				hints: [...this.tabs.getKeyHints(), bindingHint("tui.select.cancel", "close")],
+			},
+			border: "box",
+		};
+		this.panel = new ToolPanel(theme, this.config);
+	}
+
+	handleInput(data: string): void {
+		if (this.keybindings.matches(data, "tui.select.cancel")) {
+			this.done(undefined);
+			return;
+		}
+		this.tabs.handleInput(data);
+		const snapshot = this.snapshots.find((item) => item.label === this.tabs.getActiveId()) ?? this.snapshots[0];
+		this.config.secondary = snapshot.secondary;
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+}
+
+class SavingsBody implements Component {
+	private readonly theme: Theme;
+	private readonly snapshot: ReadSavingsSnapshot;
+
+	constructor(theme: Theme, snapshot: ReadSavingsSnapshot) {
+		this.theme = theme;
+		this.snapshot = snapshot;
+	}
+
+	render(width: number): string[] {
+		const avoided = Math.max(0, this.snapshot.baselineTokens - this.snapshot.returnedTokens);
+		const reduction = this.snapshot.baselineTokens > 0 ? avoided / this.snapshot.baselineTokens : 0;
+		return [
+			this.theme.bold("Tokens"),
+			metricRow("Without cache", formatTokens(this.snapshot.baselineTokens), width),
+			metricRow("With cache", formatTokens(this.snapshot.returnedTokens), width),
+			metricRow(
+				"Saved",
+				this.theme.fg("success", `${formatTokens(avoided)} tokens (${Math.round(reduction * 100)}%)`),
+				width,
+			),
+			"",
+			this.theme.bold("Cost saved"),
+			metricRow("Total", this.theme.fg("success", this.theme.bold(formatCost(this.snapshot.costSaved))), width),
+			metricRow("Unchanged", formatCost(this.snapshot.unchangedCost), width),
+			metricRow("Changes only", formatCost(this.snapshot.diffCost), width),
+			"",
+			this.theme.bold("Read results"),
+			countRow("Full", this.snapshot.counts.baseline, "Unchanged", this.snapshot.counts.unchanged, width),
+			countRow("Changes", this.snapshot.counts.diff, "Recovery", this.snapshot.counts.recovery, width),
+			"",
+			truncateToWidth(
+				this.theme.fg("dim", "Estimates include repeated chat history and prompt caching."),
+				width,
+				"",
+			),
+		];
+	}
+
+	invalidate(): void {}
+}
+
+function formatTokens(value: number): string {
+	if (value >= 1_000_000) return `~${(value / 1_000_000).toFixed(2)}M`;
+	if (value >= 1_000) return `~${Math.round(value / 1_000)}k`;
+	return `~${Math.max(0, Math.round(value))}`;
+}
+
+function formatCost(value: number): string {
+	if (value > 0 && value < 0.01) return "<$0.01";
+	return `~$${Math.max(0, value).toFixed(2)}`;
+}
+
+function metricRow(label: string, value: string, width: number): string {
+	return truncateToWidth(`${label.padEnd(16)}${value}`, width, "");
+}
+
+function countRow(left: string, leftCount: number, right: string, rightCount: number, width: number): string {
+	return truncateToWidth(
+		`${left.padEnd(11)}${String(leftCount).padEnd(6)}${right.padEnd(11)}${rightCount}`,
+		width,
+		"",
+	);
+}

package/extensions/explore/read-stats.ts

@@ -0,0 +1,120 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { readMetaFromMessage, type ReadCacheMode } from "./read-cache.ts";
+import { createReadStatsPanel, type ReadSavingsSnapshot } from "./read-stats-panel.ts";
+
+interface ContextTotals {
+	baseline: number;
+	returned: number;
+	unchangedSaved: number;
+	diffSaved: number;
+}
+
+export async function showReadStats(ctx: ExtensionCommandContext): Promise<void> {
+	const entries = ctx.sessionManager.getEntries();
+	const branchIds = new Set(ctx.sessionManager.getBranch().map((entry) => entry.id));
+	const current = calculateSnapshot(entries, branchIds, "Current chat");
+	const whole = calculateSnapshot(entries, undefined, "Whole session");
+	await ctx.ui.custom(
+		(tui, theme, keybindings, done) => createReadStatsPanel(tui, theme, keybindings, done, current, whole),
+		{
+			overlay: true,
+			overlayOptions: { anchor: "center", width: "54%", minWidth: 50, maxHeight: "85%", margin: 2 },
+		},
+	);
+}
+
+function calculateSnapshot(
+	entries: readonly unknown[],
+	includedIds: ReadonlySet<string> | undefined,
+	label: string,
+): ReadSavingsSnapshot {
+	const states = new Map<string, ContextTotals>();
+	const counts: Record<ReadCacheMode, number> = { baseline: 0, recovery: 0, unchanged: 0, diff: 0 };
+	let baselineTokens = 0;
+	let returnedTokens = 0;
+	let costSaved = 0;
+	let unchangedCost = 0;
+	let diffCost = 0;
+	let readCount = 0;
+
+	for (const entry of entries) {
+		if (!isRecord(entry) || typeof entry.id !== "string") continue;
+		const parent = typeof entry.parentId === "string" ? states.get(entry.parentId) : undefined;
+		const state: ContextTotals = parent
+			? { ...parent }
+			: { baseline: 0, returned: 0, unchangedSaved: 0, diffSaved: 0 };
+		if (entry.type === "compaction") {
+			state.baseline = 0;
+			state.returned = 0;
+			state.unchangedSaved = 0;
+			state.diffSaved = 0;
+		}
+
+		if (entry.type === "message" && "message" in entry) {
+			const meta = readMetaFromMessage(entry.message);
+			if (meta) {
+				state.baseline += meta.baselineTokens;
+				state.returned += meta.returnedTokens;
+				const saved = Math.max(0, meta.baselineTokens - meta.returnedTokens);
+				if (meta.mode === "unchanged") state.unchangedSaved += saved;
+				if (meta.mode === "diff") state.diffSaved += saved;
+				if (!includedIds || includedIds.has(entry.id)) {
+					counts[meta.mode] += 1;
+					readCount += 1;
+				}
+			}
+
+			if ((!includedIds || includedIds.has(entry.id)) && isAssistantMessage(entry.message)) {
+				baselineTokens += state.baseline;
+				returnedTokens += state.returned;
+				const inputTokens =
+					entry.message.usage.input + entry.message.usage.cacheRead + entry.message.usage.cacheWrite;
+				const inputCost =
+					entry.message.usage.cost.input +
+					entry.message.usage.cost.cacheRead +
+					entry.message.usage.cost.cacheWrite;
+				const costPerToken = inputTokens > 0 ? inputCost / inputTokens : 0;
+				unchangedCost += state.unchangedSaved * costPerToken;
+				diffCost += state.diffSaved * costPerToken;
+				costSaved += (state.baseline - state.returned) * costPerToken;
+			}
+		}
+		states.set(entry.id, state);
+	}
+
+	return {
+		label,
+		secondary: `${readCount} read${readCount === 1 ? "" : "s"} ${label === "Current chat" ? "in this chat" : "across everything done in this session"}`,
+		baselineTokens,
+		returnedTokens,
+		costSaved,
+		unchangedCost,
+		diffCost,
+		counts,
+	};
+}
+
+function isAssistantMessage(value: unknown): value is {
+	role: "assistant";
+	usage: {
+		input: number;
+		cacheRead: number;
+		cacheWrite: number;
+		cost: { input: number; cacheRead: number; cacheWrite: number };
+	};
+} {
+	if (!isRecord(value) || value.role !== "assistant" || !isRecord(value.usage)) return false;
+	if (!isRecord(value.usage.cost)) return false;
+	return (
+		typeof value.usage.input === "number" &&
+		typeof value.usage.cacheRead === "number" &&
+		typeof value.usage.cacheWrite === "number" &&
+		typeof value.usage.cost.input === "number" &&
+		typeof value.usage.cost.cacheRead === "number" &&
+		typeof value.usage.cost.cacheWrite === "number"
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}