@oai404iao/pi-subagent 0.2.0 → 0.4.0-alpha.0

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

@@ -32,6 +32,11 @@ interface AgentManifest {
 	files: Record<string, string>;
 }
 
+type ManifestReadResult =
+	| { kind: "missing" }
+	| { kind: "valid"; manifest: AgentManifest }
+	| { kind: "corrupt"; diagnostic: string };
+
 interface BundledAgentFile {
 	name: string;
 	content: Buffer;
@@ -182,53 +187,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,15 +432,46 @@ 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: [],
+			preserved: [],
+			backups: [],
+			diagnostics: [manifestRead.diagnostic],
+		};
+	}
+	const previous = manifestRead.kind === "valid" ? manifestRead.manifest : undefined;
+
+	// 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) {
+		return {
+			packageVersion,
+			userAgentsDir,
+			manifestPath,
+			installed: [],
+			updated: [],
+			removed: [],
+			preserved: [],
+			backups: [],
+			diagnostics,
+		};
+	}
+
 	const files = bundledAgentFiles(options.bundledDir);
 	const currentNames = new Set(files.map((file) => file.name));
 	const preserved: string[] = [];
 	const actions: PlannedAction[] = [];
 
-	// Plan the complete operation before changing any user agent file. A current
-	// manifest/source pair means ordinary restarts do not even read user content.
+	// Plan the complete first-install or version-change operation before
+	// changing any user agent file.
 	for (const file of files) {
 		const destination = join(userAgentsDir, file.name);
 		const destinationState = destinationKind(destination);
@@ -468,13 +486,6 @@ function syncBundledAgentsLocked(
 			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)

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 {
-	id: string;
+	agentId: string;
+	piSessionId: string;
 	sessionFile: string;
 	descriptor: SubagentDescriptor;
+	pendingMessages: number;
+	unreadUpdatesByChild: Map<string, number>;
 }
 
 export interface PersistedCatalog {
@@ -44,7 +52,7 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 				if (headerParent !== folded.descriptor.parentSessionFile) {
 					diagnostics.push({
 						kind: "diagnostic",
-						id: manager.getSessionId(),
+						piSessionId: manager.getSessionId(),
 						reason: "corrupt",
 						sessionFile: info.path,
 						...(headerParent ? { parentSessionFile: headerParent } : {}),
@@ -52,16 +60,57 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 					});
 					return;
 				}
+				let pendingMessages = 0;
+				if (folded.descriptor.runtime.backgroundProtocol === "mailbox-v2") {
+					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({
-					id: manager.getSessionId(),
+					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;
 				diagnostics.push({
 					kind: "diagnostic",
-					id: manager.getSessionId(),
+					piSessionId: manager.getSessionId(),
 					reason: "corrupt",
 					sessionFile: info.path,
 					...(headerParent ? { parentSessionFile: headerParent } : {}),
@@ -71,7 +120,7 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 		} catch (error) {
 			diagnostics.push({
 				kind: "diagnostic",
-				id: info.id,
+				piSessionId: info.id,
 				reason: "unavailable",
 				sessionFile: info.path,
 				...(info.parentSessionPath ? { parentSessionFile: info.parentSessionPath } : {}),
@@ -82,8 +131,11 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 
 	descriptors.sort(
 		(left, right) =>
-			left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) || left.id.localeCompare(right.id),
+			left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) ||
+			left.agentId.localeCompare(right.agentId),
+	);
+	diagnostics.sort((left, right) =>
+		left.piSessionId.localeCompare(right.piSessionId),
 	);
-	diagnostics.sort((left, right) => left.id.localeCompare(right.id));
 	return { descriptors, diagnostics };
 }