@oai404iao/pi-subagent 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oai404iao/pi-subagent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Durable, continuable subagents for Pi with spawn/fork providers and lifecycle controls.",
   "repository": {
     "type": "git",
@@ -27,24 +27,24 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./index.ts"
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.84.2",
-    "@earendil-works/pi-ai": ">=0.84.2",
-    "@earendil-works/pi-coding-agent": ">=0.84.2",
-    "@earendil-works/pi-tui": ">=0.84.2",
+    "@earendil-works/pi-agent-core": ">=0.85.1",
+    "@earendil-works/pi-ai": ">=0.85.1",
+    "@earendil-works/pi-coding-agent": ">=0.85.1",
+    "@earendil-works/pi-tui": ">=0.85.1",
     "typebox": "*"
   },
   "optionalDependencies": {
-    "@oai404iao/pi-codex-minimal-tools": "1.4.0"
+    "@oai404iao/pi-codex-minimal-tools": "2.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.84.2",
-    "@earendil-works/pi-ai": "^0.84.2",
-    "@earendil-works/pi-coding-agent": "^0.84.2",
-    "@earendil-works/pi-tui": "^0.84.2",
+    "@earendil-works/pi-agent-core": "0.85.1",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "^26.2.0",
     "tsx": "^4.20.6",
     "typebox": "^1.1.24",
@@ -56,6 +56,7 @@
     "check": "npm run typecheck && npm test"
   },
   "files": [
+    "index.ts",
     "agents/",
     "LICENSES/",
     "provenance/",
@@ -87,5 +88,5 @@
       "optional": true
     }
   },
-  "gitHead": "a93559be8f8b02739310c492b36270b13607fbf9"
+  "gitHead": "88cb6f56447d88b71232cd764ca5b29251341d23"
 }

package/src/agent-state.ts

@@ -0,0 +1,125 @@
+import type {
+	DelegationDetails,
+	SubagentStopReason,
+} from "./types.ts";
+
+export type AgentLifecycleState = "open" | "closed";
+export type AgentResidencyState = "resident" | "unloaded";
+
+export type AgentTurnState =
+	| { state: "none" }
+	| { state: "queued"; turnId: string }
+	| { state: "running"; turnId: string }
+	| { state: "completed"; turnId: string }
+	| { state: "errored"; turnId: string }
+	| { state: "interrupted"; turnId: string };
+
+export interface AgentControlState {
+	lifecycle: AgentLifecycleState;
+	residency: AgentResidencyState;
+	turn: AgentTurnState;
+}
+
+export function createAgentControlState(): AgentControlState {
+	return {
+		lifecycle: "open",
+		residency: "resident",
+		turn: { state: "none" },
+	};
+}
+
+export function queueAgentTurn(state: AgentControlState, turnId: string): void {
+	if (state.turn.state === "queued" || state.turn.state === "running") {
+		throw new Error(`agent turn ${state.turn.turnId} is already active`);
+	}
+	state.turn = { state: "queued", turnId };
+}
+
+export function startAgentTurn(state: AgentControlState, turnId: string): void {
+	if (state.turn.state !== "queued" || state.turn.turnId !== turnId) {
+		throw new Error(`agent turn ${turnId} was not queued`);
+	}
+	state.turn = { state: "running", turnId };
+}
+
+export function finishAgentTurn(
+	state: AgentControlState,
+	turnId: string,
+	stopReason: SubagentStopReason,
+): void {
+	if (
+		(state.turn.state !== "queued" &&
+			state.turn.state !== "running" &&
+			state.turn.state !== "interrupted") ||
+		state.turn.turnId !== turnId
+	) {
+		throw new Error(`agent turn ${turnId} is not active`);
+	}
+	switch (stopReason) {
+		case "completed":
+			state.turn = { state: "completed", turnId };
+			return;
+		case "aborted":
+			state.turn = { state: "interrupted", turnId };
+			return;
+		case "error":
+		case "max-tokens":
+			state.turn = { state: "errored", turnId };
+			return;
+	}
+}
+
+export function interruptAgentTurn(state: AgentControlState): void {
+	if (state.turn.state === "queued" || state.turn.state === "running") {
+		state.turn = { state: "interrupted", turnId: state.turn.turnId };
+	}
+}
+
+export function setAgentResidency(
+	state: AgentControlState,
+	residency: AgentResidencyState,
+): void {
+	state.residency = residency;
+}
+
+export function closeAgent(state: AgentControlState): void {
+	state.lifecycle = "closed";
+}
+
+export function currentAgentTurnId(state: AgentControlState): string | undefined {
+	return state.turn.state === "none" ? undefined : state.turn.turnId;
+}
+
+export function delegationStatus(
+	state: AgentControlState,
+	hasOwnedChildren: boolean,
+): DelegationDetails["status"] {
+	switch (state.turn.state) {
+		case "none":
+		case "queued":
+			return "starting";
+		case "running":
+			return "running";
+		case "completed":
+			return hasOwnedChildren ? "waiting" : "completed";
+		case "errored":
+		case "interrupted":
+			return hasOwnedChildren ? "waiting" : "failed";
+	}
+}
+
+export function catalogStatus(
+	state: AgentControlState,
+): "running" | "idle" | "ready" {
+	if (state.residency === "unloaded") return "ready";
+	switch (state.turn.state) {
+		case "queued":
+		case "running":
+			return "running";
+		case "none":
+		case "completed":
+		case "errored":
+		case "interrupted":
+			return "idle";
+	}
+}

package/src/agent-sync.ts

@@ -30,8 +30,18 @@ interface AgentManifest {
 	version: 1;
 	packageVersion: string;
 	files: Record<string, string>;
+	/**
+	 * Bundled preset names the user deleted. Initialization never restores
+	 * them, so deleting a preset stays effective across package versions.
+	 */
+	retired: string[];
 }
 
+type ManifestReadResult =
+	| { kind: "missing" }
+	| { kind: "valid"; manifest: AgentManifest }
+	| { kind: "corrupt"; diagnostic: string };
+
 interface BundledAgentFile {
 	name: string;
 	content: Buffer;
@@ -69,7 +79,14 @@ export interface AgentSyncResult {
 	manifestPath: string;
 	installed: string[];
 	updated: string[];
+	/** Bundled presets retired upstream and removed from the user directory. */
 	removed: string[];
+	/** Presets the user deleted; initialization keeps them absent. */
+	retired: string[];
+	/** Previously deleted presets that reappeared on disk as managed again. */
+	restored: string[];
+	/** True when this run recorded a new deletion or a recreation. */
+	retirementChanged: boolean;
 	preserved: string[];
 	backups: AgentBackup[];
 	diagnostics: string[];
@@ -130,10 +147,27 @@ function parseManifest(value: unknown, manifestPath: string): AgentManifest {
 		}
 		files[name] = hash;
 	}
+	const retired: string[] = [];
+	if (input.retired !== undefined) {
+		if (!Array.isArray(input.retired)) {
+			throw new Error("retired must be an array of bundled preset file names");
+		}
+		for (const name of input.retired) {
+			if (
+				typeof name !== "string" ||
+				basename(name) !== name ||
+				!name.endsWith(".md")
+			) {
+				throw new Error(`retired contains an invalid entry for "${String(name)}"`);
+			}
+			if (!retired.includes(name)) retired.push(name);
+		}
+	}
 	return {
 		version: MANIFEST_VERSION,
 		packageVersion: input.packageVersion.trim(),
 		files,
+		retired,
 	};
 }
 
@@ -182,53 +216,35 @@ function bundledAgentFiles(bundledDir: string): BundledAgentFile[] {
 	return files;
 }
 
-function readPreviousManifest(manifestPath: string): AgentManifest | undefined {
-	if (!existsSync(manifestPath)) return undefined;
+function readPreviousManifest(manifestPath: string): ManifestReadResult {
+	if (!existsSync(manifestPath)) return { kind: "missing" };
+	let content: Buffer | undefined;
 	try {
-		return parseManifest(JSON.parse(readFileSync(manifestPath, "utf8")), manifestPath);
+		content = readFileSync(manifestPath);
+		const manifest = parseManifest(JSON.parse(content.toString("utf8")), manifestPath);
+		return { kind: "valid", manifest };
 	} catch (error) {
-		const corruptPath = `${manifestPath}.corrupt-${timestamp()}-${randomUUID().slice(0, 8)}`;
-		copyFileSync(manifestPath, corruptPath);
-		throw new Error(
-			`${manifestPath}: invalid manifest; a copy was preserved at ${corruptPath}: ${
-				error instanceof Error ? error.message : String(error)
-			}`,
-		);
-	}
-}
-
-/**
- * Identify untouched files created by the old opt-out synchronizer without
- * changing the user filesystem. Direct bundled discovery can then use newer
- * package definitions while real user edits continue to override them.
- */
-export function unmodifiedManagedAgentNames(agentDir: string): Set<string> {
-	const manifestPath = join(agentDir, STATE_DIR_NAME, MANIFEST_FILE_NAME);
-	if (!existsSync(manifestPath)) return new Set();
-
-	let manifest: AgentManifest;
-	try {
-		manifest = parseManifest(JSON.parse(readFileSync(manifestPath, "utf8")), manifestPath);
-	} catch {
-		// A malformed historical manifest must never cause a default read-only
-		// session to hide user files or rewrite state.
-		return new Set();
-	}
-
-	const unmodified = new Set<string>();
-	const userAgentsDir = join(agentDir, "agents");
-	for (const [name, expectedHash] of Object.entries(manifest.files)) {
+		const fingerprint =
+			typeof content === "undefined"
+				? randomUUID().slice(0, 12)
+				: hash(content).slice(0, 12);
+		const corruptPath = `${manifestPath}.corrupt-${fingerprint}`;
+		let preservation = `a copy was preserved at ${corruptPath}`;
 		try {
-			const path = join(userAgentsDir, name);
-			if (lstatSync(path).isFile() && hash(readFileSync(path)) === expectedHash) {
-				unmodified.add(name);
-			}
-		} catch {
-			// Missing, unreadable, or replaced paths are user-controlled and
-			// therefore remain visible to discovery.
+			if (!existsSync(corruptPath)) copyFileSync(manifestPath, corruptPath);
+		} catch (backupError) {
+			preservation = `the corrupt file could not be copied: ${
+				backupError instanceof Error ? backupError.message : String(backupError)
+			}`;
 		}
+		return {
+			kind: "corrupt",
+			diagnostic:
+				`${manifestPath}: invalid manifest; bundled-template initialization was skipped and user/project agents remain available; ${preservation}: ${
+					error instanceof Error ? error.message : String(error)
+				}`,
+		};
 	}
-	return unmodified;
 }
 
 function sleepSync(milliseconds: number): void {
@@ -445,71 +461,135 @@ function syncBundledAgentsLocked(
 	manifestPath: string,
 ): AgentSyncResult {
 	const diagnostics: string[] = [];
-	const previous = readPreviousManifest(manifestPath);
-	const packageChanged = previous !== undefined && previous.packageVersion !== packageVersion;
+	const manifestRead = readPreviousManifest(manifestPath);
+	if (manifestRead.kind === "corrupt") {
+		return {
+			packageVersion,
+			userAgentsDir,
+			manifestPath,
+			installed: [],
+			updated: [],
+			removed: [],
+			retired: [],
+			restored: [],
+			retirementChanged: false,
+			preserved: [],
+			backups: [],
+			diagnostics: [manifestRead.diagnostic],
+		};
+	}
+	const previous = manifestRead.kind === "valid" ? manifestRead.manifest : undefined;
+
 	const files = bundledAgentFiles(options.bundledDir);
 	const currentNames = new Set(files.map((file) => file.name));
+	const previousFiles = previous?.files ?? {};
+	const retiredNames = new Set<string>();
+	const restored: string[] = [];
+
+	// A preset that was managed before and is missing now was deleted by the
+	// user. Record that deletion at every startup so a later package version
+	// cannot resurrect it; an explicit recreation restores management.
+	for (const name of previous?.retired ?? []) {
+		if (currentNames.has(name) && existsSync(join(userAgentsDir, name))) {
+			restored.push(name);
+		}
+	}
+	for (const name of Object.keys(previousFiles)) {
+		if (!currentNames.has(name)) continue;
+		if (restored.includes(name)) continue;
+		if ((previous?.retired ?? []).includes(name)) {
+			retiredNames.add(name);
+			continue;
+		}
+		if (!existsSync(join(userAgentsDir, name))) retiredNames.add(name);
+	}
+	const recordedRetired = [...retiredNames].sort();
+	const retirementChanged =
+		restored.length > 0 ||
+		recordedRetired.join("\n") !== (previous?.retired ?? []).slice().sort().join("\n");
+
+	// The package copies are initialization templates, not a runtime fallback.
+	// Once this package version has been initialized, the user directory is
+	// authoritative: edits and deletions must survive every same-version start.
+	if (previous?.packageVersion === packageVersion && !retirementChanged) {
+		return {
+			packageVersion,
+			userAgentsDir,
+			manifestPath,
+			installed: [],
+			updated: [],
+			removed: [],
+			retired: recordedRetired,
+			restored: [],
+			retirementChanged: false,
+			preserved: [],
+			backups: [],
+			diagnostics,
+		};
+	}
+
 	const preserved: string[] = [];
 	const actions: PlannedAction[] = [];
+	const versionChanged = previous?.packageVersion !== packageVersion;
+
+	// Agent files change only on first install and package-version changes. A
+	// same-version startup that merely recorded a deletion or a recreation only
+	// rewrites the manifest below.
+	if (versionChanged) {
+		// Plan the complete operation before changing any user agent file.
+		for (const file of files) {
+			if (retiredNames.has(file.name)) continue;
+			const destination = join(userAgentsDir, file.name);
+			const destinationState = destinationKind(destination);
+			if (destinationState.kind === "missing") {
+				actions.push({
+					name: file.name,
+					kind: "install",
+					destination,
+					destinationKind: "missing",
+					content: file.content,
+				});
+				continue;
+			}
 
-	// Plan the complete operation before changing any user agent file. A current
-	// manifest/source pair means ordinary restarts do not even read user content.
-	for (const file of files) {
-		const destination = join(userAgentsDir, file.name);
-		const destinationState = destinationKind(destination);
-		if (destinationState.kind === "missing") {
+			if (
+				destinationState.kind === "file"
+				&& sameRegularFile(destination, destinationState.size, file.content)
+			) {
+				preserved.push(file.name);
+				continue;
+			}
 			actions.push({
 				name: file.name,
-				kind: "install",
+				kind: "replace",
 				destination,
-				destinationKind: "missing",
+				destinationKind: destinationState.kind,
 				content: file.content,
 			});
-			continue;
 		}
 
-		const previousHash = previous?.files[file.name];
-		const bundledChanged = previousHash === undefined || previousHash !== file.hash;
-		const refresh = previous === undefined || packageChanged || bundledChanged;
-		if (!refresh) {
-			preserved.push(file.name);
-			continue;
-		}
-		if (
-			destinationState.kind === "file" &&
-			sameRegularFile(destination, destinationState.size, file.content)
-		) {
-			preserved.push(file.name);
-			continue;
+		// Retired bundled presets must not remain silently active. They are
+		// backed up like replacements, then removed; unrelated user-defined
+		// names remain.
+		for (const name of Object.keys(previousFiles).sort((left, right) => left.localeCompare(right))) {
+			if (currentNames.has(name)) continue;
+			const destination = join(userAgentsDir, name);
+			const destinationState = destinationKind(destination);
+			if (destinationState.kind === "missing") continue;
+			actions.push({
+				name,
+				kind: "remove",
+				destination,
+				destinationKind: destinationState.kind,
+			});
 		}
-		actions.push({
-			name: file.name,
-			kind: "replace",
-			destination,
-			destinationKind: destinationState.kind,
-			content: file.content,
-		});
-	}
-
-	// Retired bundled presets must not remain silently active. They are backed
-	// up like replacements, then removed; unrelated user-defined names remain.
-	for (const name of Object.keys(previous?.files ?? {}).sort((left, right) => left.localeCompare(right))) {
-		if (currentNames.has(name)) continue;
-		const destination = join(userAgentsDir, name);
-		const destinationState = destinationKind(destination);
-		if (destinationState.kind === "missing") continue;
-		actions.push({
-			name,
-			kind: "remove",
-			destination,
-			destinationKind: destinationState.kind,
-		});
 	}
 
 	const manifest: AgentManifest = {
 		version: MANIFEST_VERSION,
 		packageVersion,
 		files: Object.fromEntries(files.map((file) => [file.name, file.hash])),
+		retired: recordedRetired,
 	};
 	const stagedPaths: string[] = [];
 	const backups: AgentBackup[] = [];
@@ -576,6 +656,9 @@ function syncBundledAgentsLocked(
 		installed: actions.filter((action) => action.kind === "install").map((action) => action.name),
 		updated: actions.filter((action) => action.kind === "replace").map((action) => action.name),
 		removed: actions.filter((action) => action.kind === "remove").map((action) => action.name),
+		retired: recordedRetired,
+		restored: [...restored].sort(),
+		retirementChanged,
 		preserved,
 		backups,
 		diagnostics,

package/src/agents.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
@@ -13,10 +13,7 @@ export interface AgentDiscoveryOptions {
 	cwd: string;
 	scope: AgentScope;
 	projectTrusted: boolean;
-	bundledDir: string;
 	agentDir?: string;
-	includeBundled?: boolean;
-	excludeUserAgentNames?: ReadonlySet<string>;
 }
 
 export interface AgentDiscoveryResult {
@@ -94,11 +91,7 @@ function loadAgentFile(filePath: string, source: AgentSource): AgentDefinition {
 	};
 }
 
-function loadDirectory(
-	dir: string,
-	source: AgentSource,
-	excludeNames?: ReadonlySet<string>,
-): { agents: AgentDefinition[]; diagnostics: string[] } {
+function loadDirectory(dir: string, source: AgentSource): { agents: AgentDefinition[]; diagnostics: string[] } {
 	if (!isDirectory(dir)) return { agents: [], diagnostics: [] };
 	const agents: AgentDefinition[] = [];
 	const diagnostics: string[] = [];
@@ -114,7 +107,6 @@ function loadDirectory(
 
 	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
 		if (!entry.name.endsWith(".md") || (!entry.isFile() && !entry.isSymbolicLink())) continue;
-		if (excludeNames?.has(entry.name)) continue;
 		const filePath = join(dir, entry.name);
 		try {
 			agents.push(loadAgentFile(filePath, source));
@@ -131,9 +123,6 @@ export function discoverAgents(options: AgentDiscoveryOptions): AgentDiscoveryRe
 			? findNearestProjectAgentsDir(options.cwd)
 			: undefined;
 	const sources: Array<{ dir: string; source: AgentSource }> = [];
-	if (options.includeBundled !== false) {
-		sources.push({ dir: options.bundledDir, source: "bundled" });
-	}
 	if (options.scope !== "project") {
 		sources.push({ dir: join(options.agentDir ?? getAgentDir(), "agents"), source: "user" });
 	}
@@ -148,11 +137,7 @@ export function discoverAgents(options: AgentDiscoveryOptions): AgentDiscoveryRe
 
 	const byName = new Map<string, AgentDefinition>();
 	for (const item of sources) {
-		const loaded = loadDirectory(
-			item.dir,
-			item.source,
-			item.source === "user" ? options.excludeUserAgentNames : undefined,
-		);
+		const loaded = loadDirectory(item.dir, item.source);
 		diagnostics.push(...loaded.diagnostics);
 		for (const agent of loaded.agents) byName.set(agent.name, agent);
 	}
@@ -168,7 +153,3 @@ export function formatAgentCatalog(agents: AgentDefinition[]): string {
 	if (agents.length === 0) return "(no agents)";
 	return agents.map((agent) => `${agent.name} (${agent.source}) — ${agent.description}`).join("\n");
 }
-
-export function hasBundledAgents(dir: string): boolean {
-	return existsSync(dir) && isDirectory(dir);
-}

package/src/catalog.ts

@@ -1,12 +1,20 @@
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { foldDescriptor } from "./descriptor.ts";
+import {
+	foldCompletionMailbox,
+	unreadCompletionCounts,
+} from "./completion-mailbox.ts";
+import { foldOwnedMailbox } from "./mailbox.ts";
 import type { SessionView } from "./providers.ts";
 import type { CatalogDiagnostic, SubagentDescriptor } from "./types.ts";
 
 export interface PersistedDescriptor {
 	agentId: string;
+	piSessionId: string;
 	sessionFile: string;
 	descriptor: SubagentDescriptor;
+	pendingMessages: number;
+	unreadUpdatesByChild: Map<string, number>;
 }
 
 export interface PersistedCatalog {
@@ -52,10 +60,49 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 					});
 					return;
 				}
+				let pendingMessages = 0;
+				const mailbox = foldOwnedMailbox(manager.getEntries(), {
+					parentAgentId: folded.descriptor.parentAgentId,
+					agentId: folded.descriptor.agentId,
+				});
+				if (mailbox.kind === "corrupt") {
+					diagnostics.push({
+						kind: "diagnostic",
+						piSessionId: manager.getSessionId(),
+						reason: "corrupt",
+						sessionFile: info.path,
+						...(headerParent ? { parentSessionFile: headerParent } : {}),
+						message: `corrupt subagent mailbox: ${mailbox.message}`,
+					});
+					return;
+				}
+				pendingMessages = mailbox.snapshot.pending.length;
+				let unreadUpdatesByChild = new Map<string, number>();
+				const completions = foldCompletionMailbox(
+					manager.getEntries(),
+					{ parentAgentId: folded.descriptor.agentId },
+				);
+				if (completions.kind === "corrupt") {
+					diagnostics.push({
+						kind: "diagnostic",
+						piSessionId: manager.getSessionId(),
+						reason: "corrupt",
+						sessionFile: info.path,
+						...(headerParent ? { parentSessionFile: headerParent } : {}),
+						message: `corrupt completion mailbox: ${completions.message}`,
+					});
+				} else {
+					unreadUpdatesByChild = unreadCompletionCounts(
+						completions.snapshot,
+					);
+				}
 				descriptors.push({
 					agentId: folded.descriptor.agentId,
+					piSessionId: manager.getSessionId(),
 					sessionFile: info.path,
 					descriptor: folded.descriptor,
+					pendingMessages,
+					unreadUpdatesByChild,
 				});
 			} else if (folded.kind === "corrupt") {
 				const headerParent = manager.getHeader()?.parentSession;