@ferris1225/pi-subagents 4.0.1 → 4.1.2

package/src/completion.ts

@@ -1,160 +1,160 @@
-/**
- * Smart batching for successful background completions.
- *
- * A short debounce coalesces sibling runs while a max-wait timer, measured from
- * the first item in the open group, bounds delivery latency. Failures are
- * intentionally handled by the caller: flush held successes, then emit the
- * failure directly so it is never delayed.
- */
-
-import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
-import { formatUsageCompact, sumUsage } from "./monitor.ts";
-import type { UsageStats } from "./rpc-run.ts";
-
-export interface CompletionBatchTimings {
-	debounceMs: number;
-	maxWaitMs: number;
-}
-
-export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
-	debounceMs: 150,
-	maxWaitMs: 1_000,
-};
-
-type TimerHandle = ReturnType<typeof setTimeout>;
-
-function unrefHandle(handle: TimerHandle): void {
-	if (
-		handle &&
-		typeof handle === "object" &&
-		"unref" in handle &&
-		typeof (handle as { unref: unknown }).unref === "function"
-	) {
-		(handle as { unref: () => void }).unref();
-	}
-}
-
-export interface CompletionBatcherOptions<T> {
-	emit: (items: T[]) => void;
-	timings?: Partial<CompletionBatchTimings>;
-}
-
-export interface CompletionBatcher<T> {
-	/** Add an item to the current debounced group. */
-	push(item: T): void;
-	/** Emit any held items immediately as one group. */
-	flush(): void;
-	/** Clear timers and return held items without emitting them. */
-	dispose(): T[];
-}
-
-export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
-	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
-	let pending: T[] = [];
-	let debounceTimer: TimerHandle | null = null;
-	let maxWaitTimer: TimerHandle | null = null;
-
-	const clearTimers = (): void => {
-		if (debounceTimer !== null) {
-			clearTimeout(debounceTimer);
-			debounceTimer = null;
-		}
-		if (maxWaitTimer !== null) {
-			clearTimeout(maxWaitTimer);
-			maxWaitTimer = null;
-		}
-	};
-
-	const emitGroup = (): void => {
-		clearTimers();
-		if (pending.length === 0) return;
-		const items = pending;
-		pending = [];
-		options.emit(items);
-	};
-
-	return {
-		push(item: T): void {
-			pending.push(item);
-
-			if (debounceTimer !== null) clearTimeout(debounceTimer);
-			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
-			unrefHandle(debounceTimer);
-
-			if (maxWaitTimer === null) {
-				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
-				unrefHandle(maxWaitTimer);
-			}
-		},
-		flush: emitGroup,
-		dispose(): T[] {
-			clearTimers();
-			const abandoned = pending;
-			pending = [];
-			return abandoned;
-		},
-	};
-}
-
-export interface CompletionMessageItem {
-	agent: string;
-	block: string;
-	triggerTurn: boolean;
-	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
-	usage?: UsageStats;
-}
-
-/** Keep the established single-result shape; add a group header and an aggregate
- * token/cost footer only for real groups. */
-export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
-	if (items.length === 0) return "";
-	if (items.length === 1) return items[0].block;
-	const agents = items.map((item) => item.agent).join(", ");
-	const withUsage = items.filter((item) => item.usage !== undefined);
-	const totals = withUsage.length > 0 ? formatUsageCompact(sumUsage(withUsage.map((item) => item.usage!))) : "";
-	const footer = totals ? `\n\nTotals: ${items.length} runs · ${totals}` : "";
-	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
-}
-
-/** A grouped completion wakes the main agent when any member requires a turn. */
-export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
-	return items.some((item) => item.triggerTurn);
-}
-
-/** Passing reviewer notifications may opt out of waking; every other result wakes. */
-export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
-	if (isFailedResult(result)) return true;
-	return !(
-		notifyOnReviewPass &&
-		result.agent === "reviewer" &&
-		reviewVerdict(getResultOutput(result)) === "pass"
-	);
-}
-
-/** Minimal shape of an active run, for the "others still running" footer. Kept
- * decoupled from the monitor's RunView so this stays a pure, easily tested
- * formatter; the caller maps its live runs into this shape. */
-export interface ActiveRunFoot {
-	id: number;
-	agent: string;
-	/** Optional content label (task-derived) shown next to the agent name. */
-	label?: string;
-}
-
-/**
- * Footer appended to a completion message when OTHER runs are still active, so
- * the main agent does not declare the overall task done prematurely. A result
- * arriving for one run does not mean sibling runs are finished; naming them
- * gives the main agent concrete, in-context awareness to keep waiting.
- *
- * Returns "" when nothing is active (the common, single-run case stays quiet).
- */
-export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
-	if (runs.length === 0) return "";
-	const listed = runs.slice(0, maxListed);
-	const items = listed
-		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
-		.join(", ");
-	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
-	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
-}
+/**
+ * Smart batching for successful background completions.
+ *
+ * A short debounce coalesces sibling runs while a max-wait timer, measured from
+ * the first item in the open group, bounds delivery latency. Failures are
+ * intentionally handled by the caller: flush held successes, then emit the
+ * failure directly so it is never delayed.
+ */
+
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import { formatUsageCompact, sumUsage } from "./monitor.ts";
+import type { UsageStats } from "./rpc-run.ts";
+
+export interface CompletionBatchTimings {
+	debounceMs: number;
+	maxWaitMs: number;
+}
+
+export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
+	debounceMs: 150,
+	maxWaitMs: 1_000,
+};
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+function unrefHandle(handle: TimerHandle): void {
+	if (
+		handle &&
+		typeof handle === "object" &&
+		"unref" in handle &&
+		typeof (handle as { unref: unknown }).unref === "function"
+	) {
+		(handle as { unref: () => void }).unref();
+	}
+}
+
+export interface CompletionBatcherOptions<T> {
+	emit: (items: T[]) => void;
+	timings?: Partial<CompletionBatchTimings>;
+}
+
+export interface CompletionBatcher<T> {
+	/** Add an item to the current debounced group. */
+	push(item: T): void;
+	/** Emit any held items immediately as one group. */
+	flush(): void;
+	/** Clear timers and return held items without emitting them. */
+	dispose(): T[];
+}
+
+export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
+	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
+	let pending: T[] = [];
+	let debounceTimer: TimerHandle | null = null;
+	let maxWaitTimer: TimerHandle | null = null;
+
+	const clearTimers = (): void => {
+		if (debounceTimer !== null) {
+			clearTimeout(debounceTimer);
+			debounceTimer = null;
+		}
+		if (maxWaitTimer !== null) {
+			clearTimeout(maxWaitTimer);
+			maxWaitTimer = null;
+		}
+	};
+
+	const emitGroup = (): void => {
+		clearTimers();
+		if (pending.length === 0) return;
+		const items = pending;
+		pending = [];
+		options.emit(items);
+	};
+
+	return {
+		push(item: T): void {
+			pending.push(item);
+
+			if (debounceTimer !== null) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
+			unrefHandle(debounceTimer);
+
+			if (maxWaitTimer === null) {
+				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
+				unrefHandle(maxWaitTimer);
+			}
+		},
+		flush: emitGroup,
+		dispose(): T[] {
+			clearTimers();
+			const abandoned = pending;
+			pending = [];
+			return abandoned;
+		},
+	};
+}
+
+export interface CompletionMessageItem {
+	agent: string;
+	block: string;
+	triggerTurn: boolean;
+	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
+	usage?: UsageStats;
+}
+
+/** Keep the established single-result shape; add a group header and an aggregate
+ * token/cost footer only for real groups. */
+export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
+	if (items.length === 0) return "";
+	if (items.length === 1) return items[0].block;
+	const agents = items.map((item) => item.agent).join(", ");
+	const withUsage = items.filter((item) => item.usage !== undefined);
+	const totals = withUsage.length > 0 ? formatUsageCompact(sumUsage(withUsage.map((item) => item.usage!))) : "";
+	const footer = totals ? `\n\nTotals: ${items.length} runs · ${totals}` : "";
+	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
+}
+
+/** A grouped completion wakes the main agent when any member requires a turn. */
+export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
+	return items.some((item) => item.triggerTurn);
+}
+
+/** Passing reviewer notifications may opt out of waking; every other result wakes. */
+export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
+	if (isFailedResult(result)) return true;
+	return !(
+		notifyOnReviewPass &&
+		result.agent === "reviewer" &&
+		reviewVerdict(getResultOutput(result)) === "pass"
+	);
+}
+
+/** Minimal shape of an active run, for the "others still running" footer. Kept
+ * decoupled from the monitor's RunView so this stays a pure, easily tested
+ * formatter; the caller maps its live runs into this shape. */
+export interface ActiveRunFoot {
+	id: number;
+	agent: string;
+	/** Optional content label (task-derived) shown next to the agent name. */
+	label?: string;
+}
+
+/**
+ * Footer appended to a completion message when OTHER runs are still active, so
+ * the main agent does not declare the overall task done prematurely. A result
+ * arriving for one run does not mean sibling runs are finished; naming them
+ * gives the main agent concrete, in-context awareness to keep waiting.
+ *
+ * Returns "" when nothing is active (the common, single-run case stays quiet).
+ */
+export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
+	if (runs.length === 0) return "";
+	const listed = runs.slice(0, maxListed);
+	const items = listed
+		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
+		.join(", ");
+	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
+	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
+}

package/src/config.ts

@@ -17,9 +17,10 @@ import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["explorer", "worker", "cleaner", "reviewer"] as const;
+export const BUILTIN_AGENT_NAMES = ["explorer", "worker", "cleaner", "documenter", "reviewer"] as const;
 
-/** Agents enabled out of the box on a fresh install. Explicit configured lists are preserved. */
+/** Agents enabled out of the box on a fresh install. Documenter remains an
+ * explicit setup choice; existing non-empty configs receive it via migration. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker", "cleaner", "reviewer"];
 
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
@@ -27,6 +28,28 @@ export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 
 const LEGACY_EXPLORER_NAME = "explore";
 const EXPLORER_NAME = "explorer";
+const CLEANER_NAME = "cleaner";
+const DOCUMENTER_NAME = "documenter";
+const REVIEWER_NAME = "reviewer";
+
+/**
+ * Stamps recorded in `announcedFeatures` by the one-time upgrade that defaults
+ * cleaner on for configs written before it shipped. The first marks a config as
+ * processed, so a later deliberate disable is not undone; the second records
+ * that cleaner was actually injected, so session start can tell the user once;
+ * the third records that reviewer model/thinking settings were actually copied,
+ * so that notice never claims an inheritance that did not happen.
+ */
+export const CLEANER_DEFAULTED_FEATURE = "cleanerDefaulted";
+export const CLEANER_AUTO_ENABLED_FEATURE = "cleanerAutoEnabled";
+export const CLEANER_INHERITED_FEATURE = "cleanerInheritedReviewer";
+
+/** One-time upgrade stamps for the pre-commit documenter role. Existing
+ * non-empty configs gain it before reviewer and inherit explorer routing; fresh
+ * installs keep it off until setup explicitly enables it. */
+export const DOCUMENTER_DEFAULTED_FEATURE = "documenterDefaulted";
+export const DOCUMENTER_AUTO_ENABLED_FEATURE = "documenterAutoEnabled";
+export const DOCUMENTER_INHERITED_FEATURE = "documenterInheritedExplorer";
 
 function migrateAgentName(name: string): string {
 	return name === LEGACY_EXPLORER_NAME ? EXPLORER_NAME : name;
@@ -49,9 +72,9 @@ export const DEFAULT_MAX_CONCURRENCY = 4;
 /** Upper bound accepted for maxConcurrency (defensive clamp). */
 export const MAX_CONCURRENCY_LIMIT = 16;
 /**
- * How many automatic worker→reviewer fix rounds run when a reviewer returns
- * REVIEW_FAIL before waking the main agent. 0 disables the auto-fix loop
- * (the main agent is woken to dispatch fixes itself). Default: 2.
+ * Maximum worker fixes after REVIEW_FAIL. Each fix is followed by optional
+ * documenter and reviewer; this cap does not suppress the initial post-writer
+ * documentation/final-review workflow. 0 disables fixes. Default: 2.
  */
 export const DEFAULT_MAX_FIX_ROUNDS = 2;
 /** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
@@ -74,8 +97,8 @@ export interface SubagentsConfig {
 	/** Optional per-agent thinking preference. Runtime clamps it to the effective model's supported levels. */
 	agentThinkingLevels: Record<string, ThinkingLevel>;
 	/**
-	 * When a review passes (REVIEW_PASS verdict), deliver it without waking the
-	 * main agent. Disabled by default so passing reviews still resume orchestration.
+	 * When a standalone review passes (REVIEW_PASS verdict), deliver it without
+	 * waking the main agent. Managed workflows always wake once at final delivery.
 	 */
 	notifyOnReviewPass: boolean;
 	/**
@@ -92,11 +115,9 @@ export interface SubagentsConfig {
 	 * one parallel `subagent` call may contain. Default: 4. */
 	maxConcurrency: number;
 	/**
-	 * Auto-fix rounds when a reviewer returns REVIEW_FAIL: the extension dispatches
-	 * a worker (briefed with the review's concrete findings) then a reviewer
-	 * re-review, repeating up to this many times before waking the main agent with
-	 * the full chain. 0 disables it (the main agent handles fixes itself).
-	 * Default: 2.
+	 * Maximum worker fixes after REVIEW_FAIL. Every fix receives the full review,
+	 * then enabled documenter/reviewer stages run. Initial post-writer docs/review
+	 * do not consume this budget. 0 disables fixes. Default: 2.
 	 */
 	maxFixRounds: number;
 	/**
@@ -106,8 +127,9 @@ export interface SubagentsConfig {
 	 */
 	idleTimeoutSec: number;
 	/**
-	 * One-time feature announcements already shown to the user. Persisted so
-	 * the notice never nags again.
+	 * One-time feature announcements already shown to the user, plus schema
+	 * upgrade stamps (e.g. the cleaner default-enable upgrade). Persisted so
+	 * notices and migrations never repeat.
 	 */
 	announcedFeatures: string[];
 }
@@ -225,7 +247,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	const maxConcurrency = clampCount(raw.maxConcurrency, MAX_CONCURRENCY_LIMIT);
 	if (maxConcurrency !== undefined) config.maxConcurrency = maxConcurrency;
 
-	// 0 disables the auto-fix loop (main agent handles fixes itself).
+	// 0 disables worker fixes, not the initial managed docs/review workflow.
 	if (typeof raw.maxFixRounds === "number" && Number.isFinite(raw.maxFixRounds)) {
 		config.maxFixRounds = Math.max(0, Math.min(MAX_FIX_ROUNDS_LIMIT, Math.round(raw.maxFixRounds)));
 	}
@@ -241,6 +263,55 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		);
 	}
 
+	// One-time upgrade for configs written before cleaner shipped: a non-empty
+	// explicit enabledAgents list gets cleaner defaulted on (inserted before
+	// reviewer, matching the fresh-install order) and inherits the reviewer's
+	// configured model and thinking level — its closest peer. The stamps make
+	// the upgrade idempotent and keep a later deliberate disable from being undone.
+	if (!config.announcedFeatures.includes(CLEANER_DEFAULTED_FEATURE)) {
+		config.announcedFeatures.push(CLEANER_DEFAULTED_FEATURE);
+		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(CLEANER_NAME)) {
+			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
+			config.enabledAgents.splice(reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex, 0, CLEANER_NAME);
+			config.announcedFeatures.push(CLEANER_AUTO_ENABLED_FEATURE);
+			let inherited = false;
+			if (!config.agentModels[CLEANER_NAME] && config.agentModels[REVIEWER_NAME]) {
+				config.agentModels[CLEANER_NAME] = config.agentModels[REVIEWER_NAME];
+				inherited = true;
+			}
+			if (!config.agentThinkingLevels[CLEANER_NAME] && config.agentThinkingLevels[REVIEWER_NAME]) {
+				config.agentThinkingLevels[CLEANER_NAME] = config.agentThinkingLevels[REVIEWER_NAME];
+				inherited = true;
+			}
+			// An old explicit list may have no reviewer overrides to copy; only the
+			// copied case is stamped so the one-time notice stays accurate.
+			if (inherited) config.announcedFeatures.push(CLEANER_INHERITED_FEATURE);
+		}
+	}
+
+	if (!config.announcedFeatures.includes(DOCUMENTER_DEFAULTED_FEATURE)) {
+		config.announcedFeatures.push(DOCUMENTER_DEFAULTED_FEATURE);
+		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(DOCUMENTER_NAME)) {
+			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
+			config.enabledAgents.splice(
+				reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex,
+				0,
+				DOCUMENTER_NAME,
+			);
+			config.announcedFeatures.push(DOCUMENTER_AUTO_ENABLED_FEATURE);
+			let inherited = false;
+			if (!config.agentModels[DOCUMENTER_NAME] && config.agentModels[EXPLORER_NAME]) {
+				config.agentModels[DOCUMENTER_NAME] = config.agentModels[EXPLORER_NAME];
+				inherited = true;
+			}
+			if (!config.agentThinkingLevels[DOCUMENTER_NAME] && config.agentThinkingLevels[EXPLORER_NAME]) {
+				config.agentThinkingLevels[DOCUMENTER_NAME] = config.agentThinkingLevels[EXPLORER_NAME];
+				inherited = true;
+			}
+			if (inherited) config.announcedFeatures.push(DOCUMENTER_INHERITED_FEATURE);
+		}
+	}
+
 	return config;
 }