@ferris1225/pi-subagents 4.1.3 → 4.1.5

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

@@ -72,9 +72,10 @@ export const DEFAULT_MAX_CONCURRENCY = 4;
 /** Upper bound accepted for maxConcurrency (defensive clamp). */
 export const MAX_CONCURRENCY_LIMIT = 16;
 /**
- * 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.
+ * Maximum worker fixes after REVIEW_FAIL. Each fix is followed by a reviewer
+ * re-review; this cap does not suppress the post-writer review gate or its
+ * conditional/reviewer-disabled documentation fallback. 0 disables fixes.
+ * Default: 2.
  */
 export const DEFAULT_MAX_FIX_ROUNDS = 2;
 /** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
@@ -116,8 +117,8 @@ export interface SubagentsConfig {
 	maxConcurrency: number;
 	/**
 	 * 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.
+	 * then a re-review runs; any documentation sync selected after the terminal
+	 * healthy review does not consume this budget. 0 disables fixes. Default: 2.
 	 */
 	maxFixRounds: number;
 	/**
@@ -247,7 +248,8 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	const maxConcurrency = clampCount(raw.maxConcurrency, MAX_CONCURRENCY_LIMIT);
 	if (maxConcurrency !== undefined) config.maxConcurrency = maxConcurrency;
 
-	// 0 disables worker fixes, not the initial managed docs/review workflow.
+	// 0 disables worker fixes, not the independent post-writer review gate or
+	// conditional/reviewer-disabled documentation fallback.
 	if (typeof raw.maxFixRounds === "number" && Number.isFinite(raw.maxFixRounds)) {
 		config.maxFixRounds = Math.max(0, Math.min(MAX_FIX_ROUNDS_LIMIT, Math.round(raw.maxFixRounds)));
 	}