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

package/src/agent-sync.ts

@@ -30,6 +30,11 @@ 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 =
@@ -74,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[];
@@ -135,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,
 	};
 }
 
@@ -441,6 +470,9 @@ function syncBundledAgentsLocked(
 			installed: [],
 			updated: [],
 			removed: [],
+			retired: [],
+			restored: [],
+			retirementChanged: false,
 			preserved: [],
 			backups: [],
 			diagnostics: [manifestRead.diagnostic],
@@ -448,10 +480,38 @@ function syncBundledAgentsLocked(
 	}
 	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) {
+	if (previous?.packageVersion === packageVersion && !retirementChanged) {
 		return {
 			packageVersion,
 			userAgentsDir,
@@ -459,68 +519,77 @@ function syncBundledAgentsLocked(
 			installed: [],
 			updated: [],
 			removed: [],
+			retired: recordedRetired,
+			restored: [],
+			retirementChanged: false,
 			preserved: [],
 			backups: [],
 			diagnostics,
 		};
 	}
 
-	const files = bundledAgentFiles(options.bundledDir);
-	const currentNames = new Set(files.map((file) => file.name));
 	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 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);
-		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;
 		}
 
-		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[] = [];
@@ -587,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/catalog.ts

@@ -61,24 +61,22 @@ 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,
+				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}`,
 					});
-					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;
+					return;
 				}
+				pendingMessages = mailbox.snapshot.pending.length;
 				let unreadUpdatesByChild = new Map<string, number>();
 				const completions = foldCompletionMailbox(
 					manager.getEntries(),

package/src/config.ts

@@ -1,24 +1,16 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
-import type {
-	AgentScope,
-	BackgroundProtocol,
-	ReportDelivery,
-	SubagentSettings,
-} from "./types.ts";
+import type { AgentScope, RuntimeMode, SubagentSettings } from "./types.ts";
 
 export const CONFIG_FILE_NAME = "subagent.json";
 
 export const DEFAULT_SETTINGS: Readonly<SubagentSettings> = {
 	agentScope: "user",
 	maxDepth: 3,
-	enableRunInBackground: true,
-	defaultBackground: true,
+	runtimeMode: "background",
 	maxConcurrentBackgroundRuns: 4,
 	maxIdleRuntimes: 0,
-	backgroundProtocol: "legacy",
-	reportDelivery: "wakeup",
 	inheritExtensions: false,
 	openAIIdentity: false,
 	maxOutputBytes: 50 * 1024,
@@ -27,14 +19,10 @@ export const DEFAULT_SETTINGS: Readonly<SubagentSettings> = {
 const CONFIG_KEYS = new Set([
 	"$schema",
 	"agentScope",
-	"syncBundledAgents",
 	"maxDepth",
-	"enableRunInBackground",
-	"defaultBackground",
+	"runtimeMode",
 	"maxConcurrentBackgroundRuns",
 	"maxIdleRuntimes",
-	"backgroundProtocol",
-	"reportDelivery",
 	"inheritExtensions",
 	"openAIIdentity",
 	"maxOutputBytes",
@@ -91,14 +79,9 @@ function parseAgentScope(value: unknown, source: string): AgentScope {
 	throw new Error(`${source}: agentScope must be "user", "project", or "both"`);
 }
 
-function parseReportDelivery(value: unknown, source: string): ReportDelivery {
-	if (value === "wakeup" || value === "quiet") return value;
-	throw new Error(`${source}: reportDelivery must be "wakeup" or "quiet"`);
-}
-
-function parseBackgroundProtocol(value: unknown, source: string): BackgroundProtocol {
-	if (value === "legacy" || value === "mailbox-v2") return value;
-	throw new Error(`${source}: backgroundProtocol must be "legacy" or "mailbox-v2"`);
+function parseRuntimeMode(value: unknown, source: string): RuntimeMode {
+	if (value === "foreground" || value === "background") return value;
+	throw new Error(`${source}: runtimeMode must be "foreground" or "background"`);
 }
 
 function parseBoolean(value: unknown, key: string, source: string): boolean {
@@ -129,20 +112,12 @@ function applyConfig(
 	settings: SubagentSettings,
 	config: ConfigRecord,
 	source: string,
-	options: { allowSyncBundledAgents: boolean },
 ): SubagentSettings {
-	if (config.syncBundledAgents !== undefined && !options.allowSyncBundledAgents) {
-		throw new Error(`${source}: syncBundledAgents may be configured only in the user-level subagent.json`);
-	}
-	if (config.syncBundledAgents !== undefined) {
-		// Compatibility with 0.2/0.3 configuration files. Bundled templates are
-		// now always initialized on first install/version change, and this
-		// retired switch no longer controls runtime discovery or writes.
-		parseBoolean(config.syncBundledAgents, "syncBundledAgents", source);
-	}
 	return {
 		agentScope:
-			config.agentScope === undefined ? settings.agentScope : parseAgentScope(config.agentScope, source),
+			config.agentScope === undefined
+				? settings.agentScope
+				: parseAgentScope(config.agentScope, source),
 		maxDepth:
 			config.maxDepth === undefined
 				? settings.maxDepth
@@ -150,14 +125,10 @@ function applyConfig(
 						minimum: 0,
 						maximum: Number.MAX_SAFE_INTEGER,
 					}),
-		enableRunInBackground:
-			config.enableRunInBackground === undefined
-				? settings.enableRunInBackground
-				: parseBoolean(config.enableRunInBackground, "enableRunInBackground", source),
-		defaultBackground:
-			config.defaultBackground === undefined
-				? settings.defaultBackground
-				: parseBoolean(config.defaultBackground, "defaultBackground", source),
+		runtimeMode:
+			config.runtimeMode === undefined
+				? settings.runtimeMode
+				: parseRuntimeMode(config.runtimeMode, source),
 		maxConcurrentBackgroundRuns:
 			config.maxConcurrentBackgroundRuns === undefined
 				? settings.maxConcurrentBackgroundRuns
@@ -182,14 +153,6 @@ function applyConfig(
 							maximum: Number.MAX_SAFE_INTEGER,
 						},
 					),
-		backgroundProtocol:
-			config.backgroundProtocol === undefined
-				? settings.backgroundProtocol
-				: parseBackgroundProtocol(config.backgroundProtocol, source),
-		reportDelivery:
-			config.reportDelivery === undefined
-				? settings.reportDelivery
-				: parseReportDelivery(config.reportDelivery, source),
 		inheritExtensions:
 			config.inheritExtensions === undefined
 				? settings.inheritExtensions
@@ -214,7 +177,7 @@ export function loadSettings(options: LoadSettingsOptions): LoadedSettings {
 	const userPath = join(options.agentDir ?? getAgentDir(), CONFIG_FILE_NAME);
 	const userConfig = readConfig(userPath);
 	if (userConfig) {
-		settings = applyConfig(settings, userConfig, userPath, { allowSyncBundledAgents: true });
+		settings = applyConfig(settings, userConfig, userPath);
 		sources.push(userPath);
 	}
 
@@ -223,7 +186,7 @@ export function loadSettings(options: LoadSettingsOptions): LoadedSettings {
 		if (projectPath) {
 			const projectConfig = readConfig(projectPath);
 			if (projectConfig) {
-				settings = applyConfig(settings, projectConfig, projectPath, { allowSyncBundledAgents: false });
+				settings = applyConfig(settings, projectConfig, projectPath);
 				sources.push(projectPath);
 			}
 		}