@youngjurry/pi-agents 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.10.0 - 2026-09-10
+
+- Remove all automatic compatibility, path translation, and file-moving logic for legacy Agent storage.
+- Standardize storage, settings, custom-entry identifiers, widget keys, and status keys on the `pi-agents` name.
+- Document an explicit, collision-safe one-time command for users who need to migrate pre-0.10.0 sessions manually.
+- Keep fresh installations free of redundant legacy checks and writes.
+
+## 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
 
@@ -187,10 +189,8 @@ The settings file is optional, but spawning requires a model from either the tas
 - Child sessions persist under `~/.pi/agent/pi-agents/roots/<root-session-id>/sessions/` and reload lazily
 - Full final answers persist under `~/.pi/agent/pi-agents/roots/<root-session-id>/results/`
 - Each root storage group records its owning main-session file in `owner.json`
-- The former `~/.pi/agent/codex-agents/` directory and `agents-setting.json` filename migrate automatically without overwriting newer files
+- The extension reads and writes only `~/.pi/agent/pi-agents/` and `settings.json`; it contains no automatic legacy migration, archival, or deletion logic
 - Resuming an existing main session removes groups whose owning main-session file has been deleted; new sessions and `/reload` do not trigger grouped cleanup
-- Referenced legacy flat child files are migrated when their main session is resumed
-- The extension never automatically archives or deletes legacy flat files
 - Parents receive a compact completion notice instead of the full answer; use `list_agents(view="results")` or read the result file on demand
 - Notices to a busy agent are queued safely: `wait_agent` returns them in its own result, and any leftovers are delivered right after a successful recipient turn
 - `wait_agent` sends only newly queued mailbox notices to the model; its child status tree excludes the active caller, is folded in the TUI by default, and can be toggled with `Ctrl+O`
@@ -205,3 +205,109 @@ The settings file is optional, but spawning requires a model from either the tas
 - All agents share the same cwd and filesystem
 
 Use `/agents` to browse the tree and inspect read-only child transcripts. A compact live tree appears below the editor while child agents exist and shows each active agent's `provider/model` identifier and effective thinking level.
+
+## Manual migration from versions before 0.10.0
+
+Version 0.10.0 removes all runtime compatibility code for the former `codex-agents` names. Existing users who cannot see an old Agent tree, or who still have `~/.pi/agent/codex-agents/` or `agents-setting.json`, should **close every Pi process first** and run the following command once. It renames the storage/settings paths and updates the old custom-entry identifiers and persisted file paths in main and child session JSONL files. It refuses to merge conflicting old and new paths automatically.
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+import json
+import os
+import stat
+
+agent_dir = Path.home() / ".pi" / "agent"
+old_root = agent_dir / "codex-agents"
+new_root = agent_dir / "pi-agents"
+
+if old_root.exists():
+    if new_root.exists():
+        raise SystemExit(
+            f"Refusing to merge because both {old_root} and {new_root} exist. "
+            "Back them up and reconcile them manually first."
+        )
+    old_root.rename(new_root)
+
+old_settings = new_root / "agents-setting.json"
+new_settings = new_root / "settings.json"
+if old_settings.exists():
+    if new_settings.exists():
+        raise SystemExit(
+            f"Refusing to overwrite {new_settings}; reconcile it with {old_settings} manually."
+        )
+    old_settings.rename(new_settings)
+
+custom_types = {
+    "codex-agents": "pi-agents",
+    "codex-agents-state": "pi-agents-state",
+    "codex-agents-child-meta": "pi-agents-child-meta",
+    "codex-agents-fork-context": "pi-agents-fork-context",
+}
+old_prefix = str(old_root)
+new_prefix = str(new_root)
+
+
+def migrate(value):
+    changed = False
+    if isinstance(value, dict):
+        output = {}
+        for key, child in value.items():
+            if key == "customType" and isinstance(child, str) and child in custom_types:
+                output[key] = custom_types[child]
+                changed = True
+            elif key in {"sessionFile", "resultFile"} and isinstance(child, str) and (
+                child == old_prefix or child.startswith(old_prefix + os.sep)
+            ):
+                output[key] = new_prefix + child[len(old_prefix):]
+                changed = True
+            else:
+                output[key], child_changed = migrate(child)
+                changed |= child_changed
+        return output, changed
+    if isinstance(value, list):
+        output = []
+        for child in value:
+            migrated, child_changed = migrate(child)
+            output.append(migrated)
+            changed |= child_changed
+        return output, changed
+    return value, False
+
+files = set((agent_dir / "sessions").rglob("*.jsonl"))
+if new_root.exists():
+    files.update(new_root.rglob("*.jsonl"))
+
+changed_files = 0
+for file in sorted(files):
+    temporary = file.with_name(file.name + ".pi-agents-migrate")
+    touched = False
+    try:
+        with file.open("r", encoding="utf-8") as source, temporary.open("w", encoding="utf-8") as target:
+            for line in source:
+                try:
+                    value = json.loads(line)
+                except json.JSONDecodeError:
+                    target.write(line)
+                    continue
+                value, line_changed = migrate(value)
+                target.write(
+                    json.dumps(value, ensure_ascii=False, separators=(",", ":")) + "\n"
+                    if line_changed else line
+                )
+                touched |= line_changed
+        if touched:
+            os.chmod(temporary, stat.S_IMODE(file.stat().st_mode))
+            os.replace(temporary, file)
+            changed_files += 1
+        else:
+            temporary.unlink()
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+
+print(f"Migration complete: updated {changed_files} JSONL file(s). Restart Pi or run /reload.")
+PY
+```
+
+Fresh installations do not need this command.

package/control.ts

@@ -47,6 +47,7 @@ import {
 	type AgentRole,
 	type AgentRoleView,
 	type AgentTranscriptView,
+	type AgentUsageBreakdownEntry,
 	type AgentUsageReport,
 	type AgentUsageTotals,
 	type AgentView,
@@ -55,7 +56,7 @@ import {
 	type PersistedTreeState,
 	type RootBinding,
 } from "./types.ts";
-import { getAgentStorageDirectory, resolveMigratedStoragePath } from "./storage.ts";
+import { getAgentStorageDirectory } from "./storage.ts";
 
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const MIN_WAIT_TIMEOUT_MS = 10_000;
@@ -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");
@@ -309,28 +364,6 @@ export class AgentControl {
 		session.extensionRunner.setUIContext(proxiedUi, root.ctx.mode);
 	}
 
-	private migrateStoredFile(file: string | undefined, directory: string): { path: string | undefined; migrated: boolean } {
-		if (!file) return { path: undefined, migrated: false };
-		const original = path.resolve(file);
-		const source = resolveMigratedStoragePath(original);
-		const translated = source !== original;
-		const destinationDirectory = path.resolve(directory);
-		if (path.dirname(source) === destinationDirectory) return { path: source, migrated: translated };
-		const target = path.join(destinationDirectory, path.basename(source));
-		try {
-			fs.mkdirSync(destinationDirectory, { recursive: true });
-			if (fs.existsSync(source)) {
-				if (fs.existsSync(target)) throw new Error(`agent storage migration target already exists: ${target}`);
-				fs.renameSync(source, target);
-				return { path: target, migrated: true };
-			}
-			if (fs.existsSync(target)) return { path: target, migrated: true };
-		} catch {
-			// Keep the original path and fail safely during lazy loading if it becomes unavailable.
-		}
-		return { path: source, migrated: false };
-	}
-
 	private configureRootStorage(ctx: ExtensionContext, sessionId: string): void {
 		const safeSessionId = sessionId.replace(/[^a-zA-Z0-9._-]/g, "_");
 		const rootDirectory = path.join(this.rootStorageDirectory, safeSessionId);
@@ -1166,14 +1199,16 @@ 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()) {
 			try {
 				const liveManager = record.session?.sessionManager;
-				const storedFile = record.sessionFile ? resolveMigratedStoragePath(record.sessionFile) : undefined;
+				const storedFile = record.sessionFile;
 				if (!liveManager && (!storedFile || !fs.existsSync(storedFile))) {
 					unreadableSubagents++;
 					continue;
@@ -1182,7 +1217,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 +1234,8 @@ export class AgentControl {
 			main,
 			subagents,
 			combined,
+			mainBreakdown: finalizeBreakdown(mainDetails.breakdown),
+			subagentBreakdown: finalizeBreakdown(subagentBreakdown),
 			subagentCount: this.agentsByPath.size,
 			unreadableSubagents,
 		};
@@ -1337,20 +1376,14 @@ export class AgentControl {
 			if (entry.type === "custom" && entry.customType === STATE_ENTRY_TYPE && isPersistedState(entry.data)) latest = entry.data;
 		}
 		if (!latest || latest.rootSessionId !== ctx.sessionManager.getSessionId()) return;
-		let migratedAnyFile = false;
 		for (const persisted of latest.agents) {
 			const status: AgentLifecycleStatus = persisted.status === "queued" || (persisted.status === "pending_init" && Boolean(persisted.queuedMessage))
 				? "queued"
 				: persisted.status === "running" || persisted.status === "pending_init"
 					? "interrupted"
 					: persisted.status;
-			const migratedSession = this.migrateStoredFile(persisted.sessionFile, this.childSessionDirectory);
-			const migratedResult = this.migrateStoredFile(persisted.resultFile, this.agentResultDirectory);
-			migratedAnyFile ||= migratedSession.migrated || migratedResult.migrated;
 			const record: AgentRecord = {
 				...persisted,
-				sessionFile: migratedSession.path,
-				resultFile: migratedResult.path,
 				status,
 				statusMessage: status === "queued"
 					? "waiting for an execution slot"
@@ -1365,7 +1398,6 @@ export class AgentControl {
 			this.pathBySessionId.set(record.id, record.path);
 			if (record.nickname) this.usedNicknames.add(record.nickname);
 		}
-		if (migratedAnyFile) this.persistState();
 	}
 
 	private forkContextFromSessionManager(sessionManager: SessionManager): AgentMessage[] {
@@ -1388,29 +1420,10 @@ export class AgentControl {
 		if (!record.sessionFile) throw new Error(`agent ${record.path} has no persisted session file`);
 		if (!this.root) throw new Error("root session is not bound");
 		await this.evictForResidency(record.path);
-		const migratedSessionFile = resolveMigratedStoragePath(record.sessionFile);
-		if (migratedSessionFile !== record.sessionFile) {
-			record.sessionFile = migratedSessionFile;
-			this.persistState();
-		}
-		let sessionManager: SessionManager;
-		if (fs.existsSync(record.sessionFile)) {
-			sessionManager = SessionManager.open(record.sessionFile);
-		} else {
-			// Older queue releases persisted only a future path. Recreate a durable
-			// session with the recorded identity; its lost fork context is unrecoverable.
-			sessionManager = SessionManager.create(this.root.cwd, this.childSessionDirectory, { id: record.id });
-			sessionManager.appendCustomEntry(CHILD_META_ENTRY_TYPE, {
-				path: record.path,
-				parentPath: record.parentPath,
-				rootSessionId: this.root.sessionId,
-				role: record.role,
-			});
-			sessionManager.appendCustomEntry(FORK_CONTEXT_ENTRY_TYPE, { messages: [] });
-			record.sessionFile = this.persistQueuedSession(sessionManager);
-			this.persistState();
-			sessionManager = SessionManager.open(record.sessionFile);
+		if (!fs.existsSync(record.sessionFile)) {
+			throw new Error(`agent ${record.path} session file does not exist: ${record.sessionFile}`);
 		}
+		const sessionManager = SessionManager.open(record.sessionFile);
 		const forkContext = this.forkContextFromSessionManager(sessionManager);
 		const role = resolveRole(this.root.cwd, this.root.ctx.isProjectTrusted(), record.role);
 		const settingsManager = SettingsManager.create(this.root.cwd, getAgentDir());

package/index.ts

@@ -5,13 +5,19 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 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";
-const STATUS_KEY = "codex-agents";
+const WIDGET_KEY = "pi-agents-tree";
+const STATUS_KEY = "pi-agents";
 const PROMPT_MARKER = "<multi_agent_role>";
 
 function statusIcon(status: AgentLifecycleStatus): string {
@@ -85,8 +91,7 @@ class AgentTreeWidget {
 	invalidate(): void {}
 }
 
-export default function codexAgentsExtension(pi: ExtensionAPI): void {
-	const storageMigration = migrateLegacyAgentStorage();
+export default function piAgentsExtension(pi: ExtensionAPI): void {
 	const limits = resolveAgentLimits(loadAgentSettings(), getAgentSettingsPath());
 	const control = new AgentControl(
 		pi,
@@ -100,7 +105,6 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 
 	let activeContext: ExtensionContext | undefined;
 	let widgetTui: { requestRender(): void } | undefined;
-	let storageMigrationReported = false;
 
 	const updateUi = () => {
 		const ctx = activeContext;
@@ -127,13 +131,6 @@ export default function codexAgentsExtension(pi: ExtensionAPI): void {
 	pi.on("session_start", (event, ctx) => {
 		activeContext = ctx;
 		control.bindRoot(ctx);
-		if (!storageMigrationReported) {
-			storageMigrationReported = true;
-			if (storageMigration.movedEntries > 0) {
-				ctx.ui.notify(`Migrated agent storage to ~/.pi/agent/pi-agents (${storageMigration.movedEntries} entries).`, "info");
-			}
-			for (const warning of storageMigration.warnings) ctx.ui.notify(`Agent storage migration: ${warning}`, "warning");
-		}
 		const resumedExistingSession = event.reason === "resume"
 			|| (event.reason === "startup" && ctx.sessionManager.getEntries().some((entry) => entry.type === "message"));
 		if (resumedExistingSession) {
@@ -209,32 +206,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.10.0",
   "description": "Persistent in-process Codex-style multi-agent collaboration for Pi",
   "author": "youngjurry",
   "type": "module",

package/settings.ts

@@ -1,15 +1,11 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import {
 	clampThinkingLevel,
 	getSupportedThinkingLevels,
 	type Model,
 } from "@earendil-works/pi-ai";
-import {
-	getAgentSettingsPath as getCurrentAgentSettingsPath,
-	getLegacyAgentSettingsPaths,
-} from "./storage.ts";
+import { getAgentSettingsPath as getCurrentAgentSettingsPath } from "./storage.ts";
 
 export const DEFAULT_MAX_CONCURRENT_SUBAGENTS = 3;
 export const DEFAULT_MAX_RESIDENT_SUBAGENTS = 3;
@@ -56,34 +52,30 @@ export function selectAgentThinkingLevel(
 }
 
 export function loadAgentSettings(filePath = getAgentSettingsPath()): AgentSettings {
-	let resolvedPath = filePath;
-	if (!fs.existsSync(resolvedPath) && path.resolve(filePath) === path.resolve(getAgentSettingsPath())) {
-		resolvedPath = getLegacyAgentSettingsPaths().find((candidate) => fs.existsSync(candidate)) ?? resolvedPath;
-	}
-	if (!fs.existsSync(resolvedPath)) return {};
+	if (!fs.existsSync(filePath)) return {};
 
 	let value: unknown;
 	try {
-		value = JSON.parse(fs.readFileSync(resolvedPath, "utf8"));
+		value = JSON.parse(fs.readFileSync(filePath, "utf8"));
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`failed to read agent settings at ${resolvedPath}: ${message}`);
+		throw new Error(`failed to read agent settings at ${filePath}: ${message}`);
 	}
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error(`agent settings at ${resolvedPath} must contain a JSON object`);
+		throw new Error(`agent settings at ${filePath} must contain a JSON object`);
 	}
 
 	const raw = value as Record<string, unknown>;
 	const settings: AgentSettings = {};
 	if (raw.defaultModel !== undefined) {
 		if (typeof raw.defaultModel !== "string" || !raw.defaultModel.trim()) {
-			throw new Error(`defaultModel in ${resolvedPath} must be a non-empty provider/model string`);
+			throw new Error(`defaultModel in ${filePath} must be a non-empty provider/model string`);
 		}
 		settings.defaultModel = raw.defaultModel.trim();
 	}
 	if (raw.defaultThinkingLevel !== undefined) {
 		if (typeof raw.defaultThinkingLevel !== "string" || !CHILD_THINKING_LEVELS.includes(raw.defaultThinkingLevel as ThinkingLevel)) {
-			throw new Error(`defaultThinkingLevel in ${resolvedPath} must be one of: ${CHILD_THINKING_LEVELS.join(", ")}`);
+			throw new Error(`defaultThinkingLevel in ${filePath} must be one of: ${CHILD_THINKING_LEVELS.join(", ")}`);
 		}
 		settings.defaultThinkingLevel = raw.defaultThinkingLevel as ThinkingLevel;
 	}
@@ -91,7 +83,7 @@ export function loadAgentSettings(filePath = getAgentSettingsPath()): AgentSetti
 		const limit = raw[key];
 		if (limit === undefined) continue;
 		if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1) {
-			throw new Error(`${key} in ${resolvedPath} must be a positive integer`);
+			throw new Error(`${key} in ${filePath} must be a positive integer`);
 		}
 		settings[key] = limit;
 	}

package/storage.ts

@@ -1,87 +1,13 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const STORAGE_DIRECTORY_NAME = "pi-agents";
-const LEGACY_STORAGE_DIRECTORY_NAME = "codex-agents";
 const SETTINGS_FILE_NAME = "settings.json";
-const LEGACY_SETTINGS_FILE_NAME = "agents-setting.json";
-
-export interface StorageMigrationReport {
-	movedEntries: number;
-	warnings: string[];
-}
 
 export function getAgentStorageDirectory(): string {
 	return path.join(getAgentDir(), STORAGE_DIRECTORY_NAME);
 }
 
-export function getLegacyAgentStorageDirectory(): string {
-	return path.join(getAgentDir(), LEGACY_STORAGE_DIRECTORY_NAME);
-}
-
 export function getAgentSettingsPath(): string {
 	return path.join(getAgentStorageDirectory(), SETTINGS_FILE_NAME);
 }
-
-export function getLegacyAgentSettingsPaths(): string[] {
-	return [
-		path.join(getAgentStorageDirectory(), LEGACY_SETTINGS_FILE_NAME),
-		path.join(getLegacyAgentStorageDirectory(), LEGACY_SETTINGS_FILE_NAME),
-	];
-}
-
-function mergeWithoutOverwrite(source: string, destination: string, report: StorageMigrationReport): void {
-	if (!fs.existsSync(source)) return;
-	if (!fs.existsSync(destination)) {
-		fs.mkdirSync(path.dirname(destination), { recursive: true });
-		fs.renameSync(source, destination);
-		report.movedEntries++;
-		return;
-	}
-	const sourceStat = fs.statSync(source);
-	const destinationStat = fs.statSync(destination);
-	if (!sourceStat.isDirectory() || !destinationStat.isDirectory()) {
-		report.warnings.push(`storage migration left a conflicting path untouched: ${source}`);
-		return;
-	}
-	for (const entry of fs.readdirSync(source)) {
-		mergeWithoutOverwrite(path.join(source, entry), path.join(destination, entry), report);
-	}
-	try {
-		if (fs.readdirSync(source).length === 0) fs.rmdirSync(source);
-	} catch {
-		// A partial migration remains readable through the legacy path fallback.
-	}
-}
-
-/**
- * Preserve the 0.7.x upgrade path. For a fresh installation this is only an
- * existence check and performs no writes.
- */
-export function migrateLegacyAgentStorage(): StorageMigrationReport {
-	const report: StorageMigrationReport = { movedEntries: 0, warnings: [] };
-	const source = getLegacyAgentStorageDirectory();
-	const destination = getAgentStorageDirectory();
-	try {
-		mergeWithoutOverwrite(source, destination, report);
-		const legacySettings = path.join(destination, LEGACY_SETTINGS_FILE_NAME);
-		const settings = getAgentSettingsPath();
-		if (fs.existsSync(legacySettings)) mergeWithoutOverwrite(legacySettings, settings, report);
-	} catch (error) {
-		report.warnings.push(error instanceof Error ? error.message : String(error));
-	}
-	return report;
-}
-
-/** Translate paths persisted before the storage directory rename. */
-export function resolveMigratedStoragePath(file: string): string {
-	const source = path.resolve(file);
-	const legacyRoot = path.resolve(getLegacyAgentStorageDirectory());
-	if (source !== legacyRoot && !source.startsWith(`${legacyRoot}${path.sep}`)) return source;
-	// A collision-safe merge leaves the legacy source in place. Prefer the exact
-	// persisted path instead of shadowing it with a different destination file.
-	if (fs.existsSync(source)) return source;
-	const translated = path.join(getAgentStorageDirectory(), path.relative(legacyRoot, source));
-	return fs.existsSync(translated) ? translated : source;
-}

package/types.ts

@@ -2,10 +2,11 @@ import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core"
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 
-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 EXTENSION_ID = "pi-agents";
+export const STATE_ENTRY_TYPE = "pi-agents-state";
+export const CHILD_META_ENTRY_TYPE = "pi-agents-child-meta";
+export const FORK_CONTEXT_ENTRY_TYPE = "pi-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 {