@youngjurry/pi-agents 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.9.0 - 2026-09-10
+
+- Render `/agent-usage` directly in the normal TUI transcript through Pi's TUI-only custom-entry API instead of opening an overlay.
+- Add main-model and sub-agent-model usage breakdowns using the actual response model reported by each assistant call.
+- Show per-model input, output, cache reads/writes, total tokens, cost, contributing Agent-session count, and usage-record count.
+- Keep unattributable tool and summary usage in a separate `Tools/summaries` bucket.
+- Preserve strict separation from LLM context and built-in `/session` cache accounting.
+
 ## 0.8.1 - 2026-09-10
 
 - Remove automatic legacy-file archival and its full main-session scan; the extension no longer archives or deletes user session data.

package/README.md

@@ -64,7 +64,9 @@ Pi's built-in `/session` remains the authoritative view of the main Agent and it
 /agent-usage
 ```
 
-The read-only overlay reports main and child token totals, separate cache hit rates, combined tokens/cost, and any unreadable child sessions. It reads persisted child JSONL files without loading or waking their AgentSessions, does not add a main-session message, and does not alter provider-facing context. Pi currently has no extension hook that can add child tokens to built-in `/session` while excluding them from that command's cache statistics.
+The command writes a detailed report directly into the normal TUI transcript, like `/session`; it does not open an overlay. The report includes main, sub-agent, and combined input/output/cache/token/cost totals, followed by separate main-model and sub-agent-model breakdowns. Each model row shows its tokens, prompt/output/cache details, number of contributing Agent sessions, and number of usage records. Non-model tool and summary usage is kept in an explicit `Tools/summaries` bucket rather than being misattributed to a model.
+
+The report is stored as a TUI-only custom entry so it remains outside LLM context and does not affect `/session` message or token accounting. Reading the report does not load or wake child AgentSessions. Pi currently has no extension hook that can add child tokens to built-in `/session` while excluding them from that command's cache statistics.
 
 ## Tools
 

package/control.ts

@@ -47,6 +47,7 @@ import {
 	type AgentRole,
 	type AgentRoleView,
 	type AgentTranscriptView,
+	type AgentUsageBreakdownEntry,
 	type AgentUsageReport,
 	type AgentUsageTotals,
 	type AgentView,
@@ -126,23 +127,77 @@ function addUsageTotals(target: AgentUsageTotals, source: AgentUsageTotals): voi
 	target.cost += source.cost;
 }
 
-function sessionUsage(sessionManager: Pick<SessionManager, "getEntries">): AgentUsageTotals {
+interface SessionUsageDetails {
+	totals: AgentUsageTotals;
+	breakdown: Map<string, AgentUsageBreakdownEntry>;
+}
+
+function addAttributedUsage(
+	breakdown: Map<string, AgentUsageBreakdownEntry>,
+	key: string,
+	usage: Usage,
+): void {
+	let item = breakdown.get(key);
+	if (!item) {
+		item = { key, usage: emptyUsageTotals(), sessionCount: 1, operations: 0 };
+		breakdown.set(key, item);
+	}
+	addUsage(item.usage, usage);
+	item.operations++;
+}
+
+function sessionUsageDetails(sessionManager: Pick<SessionManager, "getEntries">): SessionUsageDetails {
 	const totals = emptyUsageTotals();
+	const breakdown = new Map<string, AgentUsageBreakdownEntry>();
 	for (const entry of sessionManager.getEntries()) {
 		if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
 			addUsage(totals, entry.usage);
+			addAttributedUsage(breakdown, "Tools/summaries", entry.usage);
 		}
 		if (entry.type !== "message") continue;
 		const message = entry.message;
-		if (message.role === "assistant" || message.role === "toolResult") addUsage(totals, message.usage);
+		if (message.role === "assistant") {
+			addUsage(totals, message.usage);
+			const responseModel = (message as typeof message & { responseModel?: string }).responseModel;
+			addAttributedUsage(breakdown, `${message.provider}/${responseModel ?? message.model}`, message.usage);
+		} else if (message.role === "toolResult" && message.usage) {
+			addUsage(totals, message.usage);
+			addAttributedUsage(breakdown, "Tools/summaries", message.usage);
+		}
+	}
+	return { totals, breakdown };
+}
+
+function mergeUsageBreakdown(
+	target: Map<string, AgentUsageBreakdownEntry>,
+	source: Map<string, AgentUsageBreakdownEntry>,
+): void {
+	for (const item of source.values()) {
+		let aggregate = target.get(item.key);
+		if (!aggregate) {
+			aggregate = { key: item.key, usage: emptyUsageTotals(), sessionCount: 0, operations: 0 };
+			target.set(item.key, aggregate);
+		}
+		addUsageTotals(aggregate.usage, item.usage);
+		aggregate.sessionCount += item.sessionCount;
+		aggregate.operations += item.operations;
 	}
-	return totals;
 }
 
 function normalizeCost(value: number): number {
 	return Math.round(value * 1_000_000_000) / 1_000_000_000;
 }
 
+function finalizeBreakdown(breakdown: Map<string, AgentUsageBreakdownEntry>): AgentUsageBreakdownEntry[] {
+	return [...breakdown.values()]
+		.map((item) => ({
+			...item,
+			usage: { ...item.usage, cost: normalizeCost(item.usage.cost) },
+		}))
+		.filter((item) => item.usage.total > 0 || item.usage.cost > 0)
+		.sort((left, right) => right.usage.total - left.usage.total || left.key.localeCompare(right.key));
+}
+
 function normalizeAgentName(name: string): string {
 	const normalized = name.trim();
 	if (!normalized) throw new Error("task_name must not be empty");
@@ -1166,8 +1221,10 @@ export class AgentControl {
 
 	getUsage(ctx: ExtensionContext): AgentUsageReport {
 		this.callerPath(ctx);
-		const main = sessionUsage(ctx.sessionManager);
+		const mainDetails = sessionUsageDetails(ctx.sessionManager);
+		const main = mainDetails.totals;
 		const subagents = emptyUsageTotals();
+		const subagentBreakdown = new Map<string, AgentUsageBreakdownEntry>();
 		let unreadableSubagents = 0;
 		const countedSessionIds = new Set<string>();
 		for (const record of this.agentsByPath.values()) {
@@ -1182,7 +1239,9 @@ export class AgentControl {
 				const sessionId = manager.getSessionId();
 				if (countedSessionIds.has(sessionId)) continue;
 				countedSessionIds.add(sessionId);
-				addUsageTotals(subagents, sessionUsage(manager));
+				const details = sessionUsageDetails(manager);
+				addUsageTotals(subagents, details.totals);
+				mergeUsageBreakdown(subagentBreakdown, details.breakdown);
 			} catch {
 				unreadableSubagents++;
 			}
@@ -1197,6 +1256,8 @@ export class AgentControl {
 			main,
 			subagents,
 			combined,
+			mainBreakdown: finalizeBreakdown(mainDetails.breakdown),
+			subagentBreakdown: finalizeBreakdown(subagentBreakdown),
 			subagentCount: this.agentsByPath.size,
 			unreadableSubagents,
 		};

package/index.ts

@@ -6,8 +6,15 @@ import { AgentControl } from "./control.ts";
 import { getAgentSettingsPath, loadAgentSettings, resolveAgentLimits } from "./settings.ts";
 import { createCollaborationTools } from "./tools.ts";
 import { migrateLegacyAgentStorage } from "./storage.ts";
-import { EXTENSION_ID, ROOT_PATH, type AgentLifecycleStatus, type AgentView } from "./types.ts";
-import { AgentPickerComponent, AgentTranscriptViewer, AgentUsageViewer, formatAgentUsage } from "./viewer.ts";
+import {
+	EXTENSION_ID,
+	ROOT_PATH,
+	USAGE_ENTRY_TYPE,
+	type AgentLifecycleStatus,
+	type AgentUsageReport,
+	type AgentView,
+} from "./types.ts";
+import { AgentPickerComponent, AgentTranscriptViewer, formatAgentUsage, renderAgentUsage } from "./viewer.ts";
 
 const SELF_PATH = fileURLToPath(import.meta.url);
 const WIDGET_KEY = "codex-agents-tree";
@@ -209,32 +216,25 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 		return new Text(`${header}\n${theme.fg("customMessageText", body)}`, 1, 0);
 	});
 
+	pi.registerEntryRenderer<AgentUsageReport>(USAGE_ENTRY_TYPE, (entry, _options, theme) => {
+		return entry.data ? renderAgentUsage(entry.data, theme) : undefined;
+	});
+
 	pi.registerCommand("agent-usage", {
-		description: "Show main, sub-agent, and combined token usage",
+		description: "Show detailed main and sub-agent token usage by model",
 		handler: async (_args, ctx) => {
 			activeContext = ctx;
-			let report;
+			let report: AgentUsageReport;
 			try {
 				report = control.getUsage(ctx);
 			} catch (error) {
 				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
 				return;
 			}
-			if (ctx.mode !== "tui") {
+			if (ctx.mode === "tui") {
+				pi.appendEntry(USAGE_ENTRY_TYPE, report);
+			} else {
 				ctx.ui.notify(formatAgentUsage(report), "info");
-				return;
-			}
-			const releaseUserOverlay = control.beginUserOverlay();
-			try {
-				await ctx.ui.custom<void>(
-					(_tui, theme, keybindings, done) => new AgentUsageViewer(theme, keybindings, report, done),
-					{
-						overlay: true,
-						overlayOptions: { anchor: "center", width: "62%", maxHeight: "70%", margin: 1 },
-					},
-				);
-			} finally {
-				releaseUserOverlay();
 			}
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youngjurry/pi-agents",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Persistent in-process Codex-style multi-agent collaboration for Pi",
   "author": "youngjurry",
   "type": "module",

package/types.ts

@@ -6,6 +6,7 @@ export const EXTENSION_ID = "codex-agents";
 export const STATE_ENTRY_TYPE = "codex-agents-state";
 export const CHILD_META_ENTRY_TYPE = "codex-agents-child-meta";
 export const FORK_CONTEXT_ENTRY_TYPE = "codex-agents-fork-context";
+export const USAGE_ENTRY_TYPE = "pi-agents-usage";
 export const ROOT_PATH = "/root";
 export const DIRECT_AGENT_TOOL_NAMES = [
 	"spawn_agents",
@@ -113,10 +114,19 @@ export interface AgentUsageTotals {
 	cost: number;
 }
 
+export interface AgentUsageBreakdownEntry {
+	key: string;
+	usage: AgentUsageTotals;
+	sessionCount: number;
+	operations: number;
+}
+
 export interface AgentUsageReport {
 	main: AgentUsageTotals;
 	subagents: AgentUsageTotals;
 	combined: AgentUsageTotals;
+	mainBreakdown: AgentUsageBreakdownEntry[];
+	subagentBreakdown: AgentUsageBreakdownEntry[];
 	subagentCount: number;
 	unreadableSubagents: number;
 }

package/viewer.ts

@@ -20,6 +20,7 @@ import {
 import {
 	ROOT_PATH,
 	type AgentTranscriptView,
+	type AgentUsageBreakdownEntry,
 	type AgentUsageReport,
 	type AgentUsageTotals,
 	type AgentView,
@@ -88,66 +89,65 @@ function usageCacheRate(usage: AgentUsageTotals): string {
 	return prompt > 0 ? `${((usage.cacheRead / prompt) * 100).toFixed(1)}%` : "n/a";
 }
 
+function usageLine(label: string, usage: AgentUsageTotals): string {
+	const parts = [
+		`${label}: ${usage.total.toLocaleString()} tokens`,
+		`input ${usagePromptTokens(usage).toLocaleString()}`,
+		`output ${usage.output.toLocaleString()}`,
+		`cached ${usage.cacheRead.toLocaleString()} (${usageCacheRate(usage)})`,
+	];
+	if (usage.cacheWrite > 0) parts.push(`cache write ${usage.cacheWrite.toLocaleString()}`);
+	if (usage.cost > 0) parts.push(`$${usage.cost.toFixed(3)}`);
+	return parts.join(" · ");
+}
+
+function breakdownLines(
+	title: string,
+	items: AgentUsageBreakdownEntry[],
+	sessionLabel: string,
+): string[] {
+	const lines = [title];
+	if (items.length === 0) {
+		lines.push("  (no billed usage)");
+		return lines;
+	}
+	for (const item of items) {
+		const sessions = `${item.sessionCount.toLocaleString()} ${sessionLabel}${item.sessionCount === 1 ? "" : "s"}`;
+		const operations = `${item.operations.toLocaleString()} usage record${item.operations === 1 ? "" : "s"}`;
+		lines.push(`  ${item.key}`);
+		lines.push(`    ${usageLine("Usage", item.usage)} · ${sessions} · ${operations}`);
+	}
+	return lines;
+}
+
 export function formatAgentUsage(report: AgentUsageReport): string {
+	const counted = report.subagentCount - report.unreadableSubagents;
 	const lines = [
 		"Agent Usage",
 		"",
-		`Main agent:  ${report.main.total.toLocaleString()} tokens · cache ${usageCacheRate(report.main)}`,
-		`Sub-agents:  ${report.subagents.total.toLocaleString()} tokens · cache ${usageCacheRate(report.subagents)}`,
-		`Combined:    ${report.combined.total.toLocaleString()} tokens`,
+		"Totals",
+		`  ${usageLine("Main agent", report.main)}`,
+		`  ${usageLine("Sub-agents", report.subagents)}`,
+		`  ${usageLine("Combined", report.combined)}`,
+		`  Sub-agent sessions: ${counted.toLocaleString()}/${report.subagentCount.toLocaleString()} readable`,
+		"",
+		...breakdownLines("Main-agent models", report.mainBreakdown, "session"),
 		"",
-		`Sub-agents counted: ${report.subagentCount - report.unreadableSubagents}/${report.subagentCount}`,
+		...breakdownLines("Sub-agent models", report.subagentBreakdown, "agent"),
 	];
-	if (report.combined.cost > 0) lines.push(`Combined cost: $${report.combined.cost.toFixed(3)}`);
-	if (report.unreadableSubagents > 0) lines.push(`Unreadable sessions: ${report.unreadableSubagents}`);
+	if (report.unreadableSubagents > 0) lines.push("", `Unreadable sub-agent sessions: ${report.unreadableSubagents.toLocaleString()}`);
 	return lines.join("\n");
 }
 
-export class AgentUsageViewer {
-	constructor(
-		private readonly theme: Theme,
-		private readonly keybindings: KeybindingsManager,
-		private readonly report: AgentUsageReport,
-		private readonly done: () => void,
-	) {}
-
-	handleInput(data: string): void {
-		if (this.keybindings.matches(data, "tui.select.cancel") || this.keybindings.matches(data, "tui.select.confirm")) {
-			this.done();
-		}
-	}
-
-	render(width: number): string[] {
-		const innerWidth = Math.max(1, width - 2);
-		const row = (label: string, usage: AgentUsageTotals, includeCache: boolean): string => {
-			const cache = includeCache ? ` · cache ${usageCacheRate(usage)}` : "";
-			return ` ${this.theme.fg("dim", `${label}:`)} ${usage.total.toLocaleString()} tokens${cache}`;
-		};
-		const lines = [
-			framedRule(this.theme, innerWidth, "╭", "╮"),
-			framedRow(this.theme, ` ${this.theme.fg("accent", this.theme.bold("Agent Usage"))}`, innerWidth),
-			framedRule(this.theme, innerWidth, "├", "┤"),
-			framedRow(this.theme, row("Main agent", this.report.main, true), innerWidth),
-			framedRow(this.theme, row("Sub-agents", this.report.subagents, true), innerWidth),
-			framedRow(this.theme, row("Combined", this.report.combined, false), innerWidth),
-			framedRow(this.theme, "", innerWidth),
-			framedRow(this.theme, ` ${this.theme.fg("dim", "Sub-agents counted:")} ${this.report.subagentCount - this.report.unreadableSubagents}/${this.report.subagentCount}`, innerWidth),
-		];
-		if (this.report.combined.cost > 0) {
-			lines.push(framedRow(this.theme, ` ${this.theme.fg("dim", "Combined cost:")} $${this.report.combined.cost.toFixed(3)}`, innerWidth));
-		}
-		if (this.report.unreadableSubagents > 0) {
-			lines.push(framedRow(this.theme, ` ${this.theme.fg("warning", `Unreadable sessions: ${this.report.unreadableSubagents}`)}`, innerWidth));
-		}
-		lines.push(
-			framedRule(this.theme, innerWidth, "├", "┤"),
-			framedRow(this.theme, ` ${this.theme.fg("dim", "Enter / Esc close")}`, innerWidth),
-			framedRule(this.theme, innerWidth, "╰", "╯"),
-		);
-		return lines;
-	}
-
-	invalidate(): void {}
+export function renderAgentUsage(report: AgentUsageReport, theme: Theme): Text {
+	const headings = new Set(["Agent Usage", "Totals", "Main-agent models", "Sub-agent models"]);
+	const rendered = formatAgentUsage(report)
+		.split("\n")
+		.map((line) => headings.has(line)
+			? (line === "Agent Usage" ? theme.bold(line) : theme.bold(theme.fg("accent", line)))
+			: line.startsWith("Unreadable ") ? theme.fg("warning", line) : line)
+		.join("\n");
+	return new Text(rendered, 1, 0);
 }
 
 export class AgentPickerComponent {