@youngjurry/pi-agents 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

package/README.md

@@ -189,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`
@@ -207,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

@@ -56,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;
@@ -364,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);
@@ -1230,7 +1208,7 @@ export class AgentControl {
 		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;
@@ -1398,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"
@@ -1426,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[] {
@@ -1449,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,7 +5,6 @@ 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,
@@ -17,8 +16,8 @@ import {
 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 {
@@ -92,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,
@@ -107,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;
@@ -134,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youngjurry/pi-agents",
-  "version": "0.9.0",
+  "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,10 @@ 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 = [