@ferris1225/pi-subagents 0.9.0 → 0.11.0

package/src/fixloop.ts

@@ -0,0 +1,76 @@
+/**
+ * Auto-fix loop: when a reviewer returns REVIEW_FAIL, the extension dispatches a
+ * worker (briefed with the review's concrete findings) and then a reviewer
+ * re-review, repeating up to maxFixRounds times before waking the main agent with
+ * the full chain. The reviewer stays read-only and in its own context; the loop
+ * is orchestrated by the extension layer, not by the reviewer itself, so the
+ * independence guarantee (no self-confirmation bias) is preserved.
+ *
+ * The main agent is never woken mid-loop: the reviewer's FAIL result is intercepted
+ * before delivery, the chain runs in the background, and only the final group
+ * (initial review → worker fixes → re-reviews) is delivered at the end.
+ */
+
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import type { SubagentsConfig } from "./config.ts";
+
+/**
+ * Whether a completed result should trigger the auto-fix loop instead of being
+ * delivered to the main agent. Only a REVIEW_FAIL verdict from a healthy
+ * reviewer run counts; failed processes and passing reviews are delivered
+ * normally. Loop-internal re-review results never reach this path (they are
+ * awaited inside the loop, not delivered through the completion flow).
+ */
+export function shouldTriggerFixLoop(result: SingleResult, config: SubagentsConfig): boolean {
+	if (config.maxFixRounds <= 0) return false;
+	if (result.agent !== "reviewer") return false;
+	if (isFailedResult(result)) return false;
+	return reviewVerdict(getResultOutput(result)) === "fail";
+}
+
+/**
+ * Build the worker task brief for one fix round from a reviewer's findings.
+ * The worker gets the full review text so it can address concrete file:line
+ * issues, with instructions to fix only blockers and self-verify.
+ */
+export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, maxRounds: number): string {
+	const review = getResultOutput(reviewerResult);
+	const remaining = maxRounds - round;
+	return [
+		`Auto-fix round ${round} of ${maxRounds} (triggered by a failed review).`,
+		``,
+		`A reviewer ran in an isolated context and returned REQUEST_CHANGES. Its full report:`,
+		`---`,
+		review,
+		`---`,
+		``,
+		`Fix the concrete blockers the reviewer flagged. Do NOT refactor unrelated code.`,
+		`Address every "Critical" item; address "Warnings" only if they are genuine.`,
+		`After editing, run the project's format/build/tests when they exist and report`,
+		`exactly what you changed (paths + short rationale) so a reviewer can verify.`,
+		remaining > 0
+			? `A reviewer will re-review your changes automatically after you finish.`
+			: `This is the last auto-fix round; the main agent will be woken with the full chain.`,
+	].join("\n");
+}
+
+/**
+ * The re-review brief handed to the reviewer after a worker fix round. Includes
+ * the prior review so the reviewer can verify the fixes without re-discovering
+ * the original issues.
+ */
+export function buildReReviewBrief(reviewerResult: SingleResult, round: number): string {
+	const review = getResultOutput(reviewerResult);
+	return [
+		`Re-review after auto-fix round ${round}.`,
+		``,
+		`The previous review (REQUEST_CHANGES) found these issues:`,
+		`---`,
+		review,
+		`---`,
+		``,
+		`Verify the worker's fixes address each blocker. Run \`git diff\` to see what changed.`,
+		`Classify honestly: APPROVE if blockers are resolved, REQUEST_CHANGES if not.`,
+		`End with your machine-readable verdict line as usual (VERDICT: REVIEW_PASS / REVIEW_FAIL).`,
+	].join("\n");
+}

package/src/index.ts

@@ -18,6 +18,13 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { BackgroundTaskQueue } from "./background.ts";
+import {
+	completionGroupTriggersTurn,
+	completionTriggersTurn,
+	createCompletionBatcher,
+	formatCompletionMessage,
+	type CompletionMessageItem,
+} from "./completion.ts";
 import { getConfigPath, loadConfig, loadConfigSync, saveConfig } from "./config.ts";
 import { repairUnavailableModelOverrides } from "./models.ts";
 import { buildDelegationDirective } from "./prompt.ts";
@@ -27,13 +34,17 @@ import {
 	getFinalOutput,
 	getResultOutput,
 	isFailedResult,
+	reviewVerdict,
 	runSingleAgent,
+	truncateResultOutput,
+	writeResultArtifact,
 	type SingleResult,
 	type SubagentDetails,
 	type SubagentLiveEvent,
 	type UsageStats,
 } from "./spawn.ts";
-import { formatTaskSummary, formatToolActivity, monitor, statusColor, statusIcon, statusLabel } from "./monitor.ts";
+import { buildFixTaskBrief, buildReReviewBrief, shouldTriggerFixLoop } from "./fixloop.ts";
+import { formatTaskSummary, formatToolActivity, monitor, statusColor, statusIcon, statusLabel, type RunChainMeta } from "./monitor.ts";
 
 const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
@@ -59,7 +70,7 @@ function emptyUsage(): UsageStats {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
 
-function queuedResult(agent: AgentConfig, task: string): SingleResult {
+function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
 	return {
 		agent: agent.name,
 		agentSource: agent.source,
@@ -69,6 +80,7 @@ function queuedResult(agent: AgentConfig, task: string): SingleResult {
 		stderr: "",
 		usage: emptyUsage(),
 		model: agent.model,
+		...(thinking ? { thinking } : {}),
 	};
 }
 
@@ -114,6 +126,19 @@ function formatUsage(usage: UsageStats): string {
 	return parts.join(" ");
 }
 
+function formatCompletionBlock(result: SingleResult, maxResultLines: number): string {
+	const status = isFailedResult(result) ? "failed" : "completed";
+	const usage = formatUsage(result.usage);
+	const output = getResultOutput(result);
+	const { text, truncated } = truncateResultOutput(output, maxResultLines);
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}`, "", `Task: ${formatTaskSummary(result.task)}`, "", text];
+	if (truncated) {
+		// The full text lives on disk so the main agent can read it on demand.
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent)})`);
+	}
+	return lines.join("\n");
+}
+
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
 	// Init-time decisions need the config synchronously; the full (migrating)
@@ -121,6 +146,23 @@ export default function (pi: ExtensionAPI): void {
 	const initialConfig = loadConfigSync(configPath);
 	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
 	let sessionActive = true;
+	const sendCompletionGroup = (items: CompletionMessageItem[]): void => {
+		if (!sessionActive || items.length === 0) return;
+		const message = {
+			customType: "subagent-result",
+			content: formatCompletionMessage(items),
+			display: true,
+		};
+		if (completionGroupTriggersTurn(items)) {
+			pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+		} else {
+			// No-wake delivery: nextTurn rides along with the next user turn and can
+			// never start a continuation by itself. followUp would auto-continue
+			// whenever pi is already streaming, defeating the opt-out.
+			pi.sendMessage(message, { deliverAs: "nextTurn" });
+		}
+	};
+	const completionBatcher = createCompletionBatcher<CompletionMessageItem>({ emit: sendCompletionGroup });
 
 	// Recursion guard: sub-agents at the configured depth are leaf processes and
 	// cannot delegate again. maxSubagentDepth 0 disables the tool entirely.
@@ -148,6 +190,7 @@ export default function (pi: ExtensionAPI): void {
 
 	pi.on("session_shutdown", () => {
 		sessionActive = false;
+		completionBatcher.dispose();
 		backgroundQueue.cancelAll();
 	});
 
@@ -162,11 +205,11 @@ export default function (pi: ExtensionAPI): void {
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output)."
 		].join(" "),
 		promptSnippet:
-			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent.",
+			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
 		promptGuidelines: [
-			"Use subagent to delegate discrete, self-contained tasks so the main context stays clean; do orchestration and verification yourself.",
-			"Use subagent with agent 'explore' for broad or open-ended code search before large changes.",
-			"Use subagent with agent 'worker' to implement a well-scoped task; it plans internally.",
+			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
+			"Use subagent with agent 'explore' for broad or open-ended code search before large changes; a targeted 'where is X' is a direct grep/read.",
+			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
 			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
 			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
 			"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
@@ -292,12 +335,103 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 
+			/**
+			 * Dispatch one agent inside an auto-fix chain: tracked in the widget with a
+			 * groupId/relationLabel, but NOT delivered through the completion flow — the
+			 * chain owner assembles and delivers the whole group at the end.
+			 */
+			const launchInLoop = async (
+				agentName: string,
+				task: string,
+				signal: AbortSignal,
+				meta: RunChainMeta,
+			): Promise<SingleResult> => {
+				const agent = agents.find((candidate) => candidate.name === agentName);
+				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
+				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
+				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel, meta);
+				const onLive = makeLiveHandler(runId);
+				try {
+					const result = await runSingleAgent({
+						defaultCwd: ctx.cwd,
+						agent,
+						agentName,
+						task,
+						thinkingLevel,
+						signal,
+						onLive,
+						makeDetails: makeDetails("single", true),
+					});
+					finishRun(runId, isFailedResult(result) ? "failed" : "done");
+					return result;
+				} catch (error) {
+					finishRun(runId, "failed");
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					return {
+						...queuedResult(agent, task, thinkingLevel),
+						exitCode: 1,
+						stderr: errorMessage,
+						stopReason: signal.aborted ? "aborted" : "error",
+						errorMessage,
+					};
+				}
+			};
+
+			/**
+			 * Run the auto-fix chain in the background: worker (briefed with the review's
+			 * findings) → reviewer re-review, up to maxFixRounds times. The main agent is
+			 * not woken mid-loop; the full chain is delivered as one group at the end.
+			 * Failures short-circuit: a crashed worker skips its re-review and delivers.
+			 */
+			const startFixLoop = (initialReviewerResult: SingleResult, parentGroupId: string): void => {
+				backgroundQueue.enqueue(
+					async (signal) => {
+						const chain: SingleResult[] = [initialReviewerResult];
+						let lastReviewer = initialReviewerResult;
+						for (let round = 1; round <= config.maxFixRounds; round++) {
+							if (!sessionActive) break;
+							const fixBrief = buildFixTaskBrief(lastReviewer, round, config.maxFixRounds);
+							const workerResult = await launchInLoop("worker", fixBrief, signal, {
+								groupId: parentGroupId,
+								relationLabel: `fix round ${round}`,
+							});
+							chain.push(workerResult);
+							if (!sessionActive || isFailedResult(workerResult)) break;
+							const reReviewBrief = buildReReviewBrief(lastReviewer, round);
+							const reviewResult = await launchInLoop("reviewer", reReviewBrief, signal, {
+								groupId: parentGroupId,
+								relationLabel: `re-review round ${round}`,
+							});
+							chain.push(reviewResult);
+							lastReviewer = reviewResult;
+							if (!sessionActive) break;
+							if (reviewVerdict(getResultOutput(reviewResult)) === "pass") break;
+						}
+						if (!sessionActive) return;
+						// Deliver the whole chain as one group; the loop's outcome always wakes
+						// the main agent (a passing chain reports success, a stuck one needs a human).
+						const items: CompletionMessageItem[] = chain.map((r) => ({
+							agent: r.agent,
+							block: formatCompletionBlock(r, config.maxResultLines),
+							triggerTurn: true,
+						}));
+						sendCompletionGroup(items);
+						completionBatcher.flush();
+					},
+					() => {
+						// Cancelled: each in-flight run was already finished by its launchInLoop path.
+					},
+				);
+			};
+
 			const startBackground = (agentName: string, task: string, cwd?: string): SingleResult => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 
-				const pending = queuedResult(agent, task);
-				const runId = monitor.addRun(agent.name, task, agent.model);
+				// Effective strength: config override > agent frontmatter default > global default.
+				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
+				const pending = queuedResult(agent, task, thinkingLevel);
+				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel);
 				const onLive = makeLiveHandler(runId);
 
 				backgroundQueue.enqueue(
@@ -310,7 +444,7 @@ export default function (pi: ExtensionAPI): void {
 								agentName,
 								task,
 								cwd,
-								thinkingLevel: config.thinkingLevel,
+								thinkingLevel,
 								signal: backgroundSignal,
 								onLive,
 								makeDetails: makeDetails("single", true),
@@ -328,18 +462,29 @@ export default function (pi: ExtensionAPI): void {
 						}
 
 						if (!sessionActive) return;
-						const status = isFailedResult(result) ? "failed" : "completed";
-						const usage = formatUsage(result.usage);
-						pi.sendMessage(
-							{
-								customType: "subagent-result",
-								content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\nTask: ${formatTaskSummary(result.task)}\n\n${getResultOutput(result)}`,
-								display: true,
-							},
-							// The result is both durable context and a wake-up signal. If the
-							// main agent is busy, followUp queues it until the current turn ends.
-							{ deliverAs: "followUp", triggerTurn: true },
-						);
+						// Auto-fix loop: a REVIEW_FAIL from a main-agent-dispatched reviewer
+						// triggers a worker→reviewer chain (up to maxFixRounds) without waking
+						// the main agent. Loop-internal re-reviews never reach here (they are
+						// awaited inside launchInLoop); the initial review is delivered with
+						// the chain at the end.
+						if (shouldTriggerFixLoop(result, config)) {
+							startFixLoop(result, `fix-${runId}`);
+							return;
+						}
+						const failed = isFailedResult(result);
+						const completion: CompletionMessageItem = {
+							agent: result.agent,
+							block: formatCompletionBlock(result, config.maxResultLines),
+							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
+						};
+						if (failed) {
+							// Failures never wait and never hide behind a success turn: deliver
+							// first so the wake-up leads with the failure; held successes follow.
+							sendCompletionGroup([completion]);
+							completionBatcher.flush();
+						} else {
+							completionBatcher.push(completion);
+						}
 					},
 					() => finishRun(runId, "failed"),
 				);
@@ -426,7 +571,7 @@ export default function (pi: ExtensionAPI): void {
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
 				const model = r.model ?? "?";
-				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
 				return new Text(line, 0, 0);
 			}
 
@@ -439,7 +584,7 @@ export default function (pi: ExtensionAPI): void {
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
 				const model = r.model ?? "?";
-				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
+				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
 			}
 			return new Text(lines.join("\n"), 0, 0);
 		},
@@ -473,7 +618,10 @@ export default function (pi: ExtensionAPI): void {
 						for (const r of runs) {
 							const icon = statusIcon(r.status, theme);
 							const label = theme.fg(statusColor(r.status), statusLabel(r.status));
-							lines.push(truncateToWidth(` ${icon} ${monitor.summarize(r)} · ${label}`, width, ""));
+							// Chain-internal runs (auto-fix worker/reviewer) indent under their
+							// parent reviewer; summarize() already carries the relationLabel.
+							const head = r.groupId ? theme.fg("dim", "  ↳ ") : " ";
+							lines.push(truncateToWidth(`${head}${icon} ${monitor.summarize(r)} · ${label}`, width, ""));
 							if (r.status === "queued" || r.status === "running") {
 								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task)}`), width, ""));
 							}

package/src/monitor.ts

@@ -26,6 +26,8 @@ export interface RunView {
 	agent: string;
 	task: string;
 	model?: string;
+	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
+	thinking?: string;
 	status: RunStatus;
 	usage: UsageStats;
 	/** Concise current activity ("thinking", "read src/index.ts"); last writer wins. */
@@ -34,6 +36,16 @@ export interface RunView {
 	startedAt?: number;
 	/** Epoch ms when the run finished (set on "done"/"failed"). */
 	endedAt?: number;
+	/** When set, this run belongs to an auto-fix chain (e.g. worker fixing a reviewer's findings). */
+	groupId?: string;
+	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
+	relationLabel?: string;
+}
+
+/** Optional chain metadata for runs spawned by an auto-fix loop. */
+export interface RunChainMeta {
+	groupId?: string;
+	relationLabel?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -166,15 +178,18 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	addRun(agent: string, task: string, model?: string): number {
+	addRun(agent: string, task: string, model?: string, thinking?: string, meta?: RunChainMeta): number {
 		const id = this.nextId++;
 		this.runs.push({
 			id,
 			agent,
 			task,
 			model,
+			thinking,
 			status: "queued",
 			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			...(meta?.groupId ? { groupId: meta.groupId } : {}),
+			...(meta?.relationLabel ? { relationLabel: meta.relationLabel } : {}),
 		});
 		this.notify();
 		return id;
@@ -230,7 +245,9 @@ export class MonitorStore {
 	summarize(run: RunView): string {
 		const usage = formatUsageCompact(run.usage);
 		const parts = [run.agent];
+		if (run.relationLabel) parts.push(run.relationLabel);
 		if (run.model) parts.push(run.model);
+		if (run.thinking) parts.push(`thinking ${run.thinking}`);
 		if (usage) parts.push(usage);
 		const elapsed = formatElapsed(run);
 		if (elapsed) parts.push(elapsed);

package/src/prompt.ts

@@ -16,8 +16,8 @@ import { formatCatalogEntry } from "./agents.ts";
 
 /** Compact role routing hints, emitted only for roles that are enabled. */
 const ROLE_ROUTING: Record<string, string> = {
-	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
-	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
+	explore: "explore — broad/open-ended code search, multi-file lookups (read-only, cheap); NOT for one-line lookups.",
+	worker: "worker — implement/fix/refactor/test a self-contained task worth a separate context (full tools; plans internally).",
 	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
 };
 
@@ -45,8 +45,9 @@ Available agents:
 ${catalog}
 
 ${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
-- Default to delegating every discrete task to a sub-agent; use the automatically delivered findings for orchestration and verification.
-- Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
+- Handle SIMPLE work INLINE with direct tools: a single lookup, one-line edit, or a quick question is a grep/read/edit in the main context — never a sub-agent. Sub-agents cost startup time, tokens, and a context switch.
+- Delegate only when isolation genuinely pays: broad exploration of an unfamiliar area, a self-contained implementation/fix with its own validation, or a fresh-context review gate.
+- When in doubt, start with a direct tool call in the main context; escalate to a sub-agent only if the work turns out broad.
 - For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
 ${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
 - Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.