@ferris1225/pi-subagents 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -134,7 +134,7 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number): st
 	const fallbackNote = result.modelFallbackFrom
 		? ` (model fell back from ${result.modelFallbackFrom} to ${result.model ?? "main-window model"})`
 		: "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task)}`, "", text];
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, "", 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)})`);
@@ -243,22 +243,34 @@ export default function (pi: ExtensionAPI): void {
 
 			// Finished runs leave the widget immediately. Their final findings are sent
 			// back as a custom message that automatically starts a follow-up turn.
-			const finishRun = (runId: number, status: "done" | "failed"): void => {
+			const finishRun = (
+				runId: number,
+				status: "done" | "failed",
+				opts?: { silent?: boolean; retain?: boolean },
+			): void => {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
-				const run = monitor.removeRun(runId);
+				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
 				if (!run) return; // already finished — stay idempotent
-				if (!sessionActive) return;
+				if (opts?.silent || !sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
 				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
-			// "read src/index.ts", ...), never a raw args blob.
-			const makeLiveHandler = (runId: number) => (e: SubagentLiveEvent): void => {
+			// "read src/index.ts", ...), never a raw args blob. Reviewer runs started
+			// by the main agent defer finishing so the queue task can decide between
+			// delivering the review and starting an auto-fix chain: a triggered chain
+			// keeps the parent row in the widget (annotated) until it completes and
+			// suppresses the premature "done" notification.
+			const makeLiveHandler = (runId: number, deferFinish = false) => (e: SubagentLiveEvent): void => {
 				switch (e.kind) {
 					case "status":
-						if (e.status === "done" || e.status === "failed") finishRun(runId, e.status);
-						else monitor.setStatus(runId, e.status);
+						if (e.status === "done" || e.status === "failed") {
+							// Deferred runs only update the widget; the queue task finishes
+							// them once it knows whether an auto-fix chain will follow.
+							if (deferFinish) monitor.setStatus(runId, e.status);
+							else finishRun(runId, e.status);
+						} else monitor.setStatus(runId, e.status);
 						break;
 					case "usage":
 						monitor.setUsage(runId, e.usage, e.model);
@@ -386,8 +398,10 @@ export default function (pi: ExtensionAPI): void {
 			 * 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.
+			 * The triggering reviewer's run stays visible in the widget (annotated) until
+			 * the chain resolves, so the ↳ rows have an obvious parent.
 			 */
-			const startFixLoop = (initialReviewerResult: SingleResult, parentGroupId: string): void => {
+			const startFixLoop = (initialReviewerResult: SingleResult, parentGroupId: string, parentRunId: number): void => {
 				backgroundQueue.enqueue(
 					async (signal) => {
 						const chain: SingleResult[] = [initialReviewerResult];
@@ -408,12 +422,18 @@ export default function (pi: ExtensionAPI): void {
 							});
 							chain.push(reviewResult);
 							lastReviewer = reviewResult;
-							if (!sessionActive) break;
+							// A crashed re-review must stop the chain like a crashed worker: its
+							// output (if any) is not a verdict, and feeding it to the next fix
+							// round would brief the worker from garbage.
+							if (!sessionActive || isFailedResult(reviewResult)) break;
 							if (reviewVerdict(getResultOutput(reviewResult)) === "pass") break;
 						}
+						// The chain is done (success, exhaustion, or abort): drop the retained
+						// parent row, then 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).
+						monitor.removeRun(parentRunId);
 						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),
@@ -423,7 +443,9 @@ export default function (pi: ExtensionAPI): void {
 						completionBatcher.flush();
 					},
 					() => {
-						// Cancelled: each in-flight run was already finished by its launchInLoop path.
+						// Cancelled before delivery: clean up the retained parent row (each
+						// in-flight chain run was already finished by its launchInLoop path).
+						monitor.removeRun(parentRunId);
 					},
 				);
 			};
@@ -436,7 +458,9 @@ export default function (pi: ExtensionAPI): void {
 				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);
+				// Only a main-agent-dispatched reviewer can trigger an auto-fix chain, so
+				// only its finish is deferred to the queue task (see startFixLoop).
+				const onLive = makeLiveHandler(runId, agent.name === "reviewer");
 
 				backgroundQueue.enqueue(
 					async (backgroundSignal) => {
@@ -473,12 +497,22 @@ export default function (pi: ExtensionAPI): void {
 						// 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.
+						// the chain at the end. While the chain runs, the triggering review
+						// stays in the widget (annotated) so the chain rows have an obvious
+						// parent; no premature "done" notification is shown.
 						if (shouldTriggerFixLoop(result, config)) {
-							startFixLoop(result, `fix-${runId}`);
+							// The session is known active here (checked above), so the chain
+							// always starts: keep the triggering review in the widget
+							// (annotated) without a premature "done" notification, and let
+							// startFixLoop deliver the whole chain and drop the parent row.
+							finishRun(runId, "done", { silent: true, retain: true });
+							monitor.setAnnotation(runId, "auto-fix chain running");
+							startFixLoop(result, `fix-${runId}`, runId);
 							return;
 						}
 						const failed = isFailedResult(result);
+						finishRun(runId, failed ? "failed" : "done");
+						if (!sessionActive) return;
 						const completion: CompletionMessageItem = {
 							agent: result.agent,
 							block: formatCompletionBlock(result, config.maxResultLines),
@@ -553,14 +587,14 @@ export default function (pi: ExtensionAPI): void {
 			if (args.tasks && args.tasks.length > 0) {
 				let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${args.tasks.length})`)}`;
 				for (const t of args.tasks.slice(0, 4)) {
-					const preview = t.task.length > 48 ? `${t.task.slice(0, 48)}…` : t.task;
+					const preview = formatTaskSummary(t.task, 48);
 					text += `\n  ${theme.fg("accent", t.agent)} ${theme.fg("dim", preview)}`;
 				}
 				if (args.tasks.length > 4) text += `\n  ${theme.fg("dim", `… +${args.tasks.length - 4} more`)}`;
 				return new Text(text, 0, 0);
 			}
 			const task: string = args.task ?? "";
-			const preview = task.length > 60 ? `${task.slice(0, 60)}…` : task;
+			const preview = formatTaskSummary(task, 60);
 			return new Text(
 				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")} ${theme.fg("dim", preview)}`,
 				0,
@@ -628,9 +662,10 @@ export default function (pi: ExtensionAPI): void {
 							// 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, ""));
+							const note = r.annotation ? theme.fg("dim", ` · ${r.annotation}`) : "";
+							lines.push(truncateToWidth(`${head}${icon} #${r.id} ${monitor.summarize(r)} · ${label}${note}`, width, ""));
 							if (r.status === "queued" || r.status === "running") {
-								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task)}`), width, ""));
+								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task, Math.max(20, width - 11))}`), width, ""));
 							}
 							// Activity sits one indent level below the agent name.
 							if (r.activity) lines.push(truncateToWidth(theme.fg("dim", `     ${r.activity}`), width, ""));

package/src/monitor.ts

@@ -40,6 +40,8 @@ export interface RunView {
 	groupId?: string;
 	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
 	relationLabel?: string;
+	/** Free-form note shown in the widget next to the status label (e.g. "auto-fix chain running"). */
+	annotation?: string;
 }
 
 /** Optional chain metadata for runs spawned by an auto-fix loop. */
@@ -54,23 +56,145 @@ export interface RunChainMeta {
 
 const TASK_SUMMARY_MAX = 80;
 const TASK_SUMMARY_ELLIPSIS = "…";
+/** Columns reserved at the END of a truncated summary so the distinguishing
+ * keywords (paths, symbols, ...) survive; the head gets the rest. */
+const TASK_SUMMARY_TAIL_MAX = 28;
+/** Tail share of a non-default maxWidth (narrow widgets keep a usable tail). */
+const TASK_SUMMARY_TAIL_SHARE = 0.35;
+const TASK_SUMMARY_TAIL_MIN = 8;
+const TASK_SUMMARY_KEY_SEP = " · ";
+/** kebab/snake words that are task boilerplate, never distinguishing signal. */
+const KEY_FRAGMENT_STOPWORDS = new Set([
+	"self-contained",
+	"read-only",
+	"write-only",
+	"auto-fix",
+	"re-review",
+	"one-line",
+	"pre-commit",
+]);
 const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 
-/** One-line task preview, capped by terminal display columns (including the ellipsis). */
-export function formatTaskSummary(task: string): string {
-	const oneLine = stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
-	if (visibleWidth(oneLine) <= TASK_SUMMARY_MAX) return oneLine;
+interface KeyFragment {
+	text: string;
+	index: number;
+}
 
-	const prefixMax = TASK_SUMMARY_MAX - visibleWidth(TASK_SUMMARY_ELLIPSIS);
-	let prefix = "";
-	let prefixWidth = 0;
-	for (const { segment } of graphemeSegmenter.segment(oneLine)) {
+/**
+ * Pull the most distinguishing fragments out of a task: file paths, quoted
+ * phrases, camelCase/PascalCase symbols and kebab/snake compounds. Sorted by
+ * first occurrence and deduped (a path covers its own sub-fragments). These
+ * are what make parallel tasks of the same agent look different.
+ */
+export function extractKeyFragments(text: string): string[] {
+	const fragments: KeyFragment[] = [];
+	const add = (re: RegExp, group = 0): void => {
+		for (const m of text.matchAll(re)) {
+			const g = m[group];
+			if (g === undefined) continue;
+			fragments.push({ text: g, index: m.index ?? 0 });
+		}
+	};
+	// Quoted phrases first (highest signal).
+	add(/["'`]([^"'`]{4,60})["'`]/g, 1);
+	// Paths with a known extension (src/index.ts, build/out.js.map).
+	add(/(?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,5}(?![A-Za-z0-9_.-])/g);
+	// Paths with a slash but no extension (src/components, .github/workflows).
+	add(/(?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]+(?:[\\/][A-Za-z0-9_.-]+)+(?![\\/])/g);
+	// camelCase / PascalCase identifiers (function or type names).
+	add(/\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b/g);
+	// snake_case / kebab-case compound words.
+	add(/\b[a-z][a-z0-9]+[-_][a-z0-9][a-z0-9_-]*\b/g);
+
+	fragments.sort((a, b) => a.index - b.index);
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const f of fragments) {
+		const t = f.text.trim();
+		if (t.length < 4 || KEY_FRAGMENT_STOPWORDS.has(t)) continue;
+		if (seen.has(t)) continue;
+		// A longer fragment (the full path) covers its own sub-fragments.
+		if (out.some((o) => o.includes(t) || t.includes(o))) continue;
+		seen.add(t);
+		out.push(t);
+	}
+	return out;
+}
+
+function takeGraphemes(segments: string[], maxWidth: number): string {
+	let width = 0;
+	const out: string[] = [];
+	for (const segment of segments) {
 		const segmentWidth = visibleWidth(segment);
-		if (prefixWidth + segmentWidth > prefixMax) break;
-		prefix += segment;
-		prefixWidth += segmentWidth;
+		if (width + segmentWidth > maxWidth) break;
+		out.push(segment);
+		width += segmentWidth;
+	}
+	return out.join("");
+}
+
+function tailGraphemes(segments: string[], maxWidth: number): string {
+	let width = 0;
+	const tail: string[] = [];
+	for (let i = segments.length - 1; i >= 0; i--) {
+		const segmentWidth = visibleWidth(segments[i]);
+		if (width + segmentWidth > maxWidth) break;
+		tail.unshift(segments[i]);
+		width += segmentWidth;
 	}
-	return `${prefix}${TASK_SUMMARY_ELLIPSIS}`;
+	return tail.join("");
+}
+
+/**
+ * One-line task preview, capped by `maxWidth` display columns (default 80).
+ * `keysOnly` (default): extracted key fragments (paths, quoted phrases,
+ * symbols) are shown bare — the agent name is already displayed next to the
+ * task line, so templated prose ("explore: trace how ...") adds nothing.
+ * `keysOnly: false` keeps the prose as `head…tail` (used for completion
+ * messages, where the Task line is the reader's only context).
+ * Grapheme-safe — CJK, ZWJ emoji and combining sequences are never split.
+ */
+export function formatTaskSummary(task: string, maxWidth: number = TASK_SUMMARY_MAX, keysOnly = true): string {
+	const oneLine = stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
+	if (maxWidth <= 0 || visibleWidth(oneLine) <= maxWidth) return oneLine;
+
+	const segments = [...graphemeSegmenter.segment(oneLine)].map((s) => s.segment);
+	const ellipsisWidth = visibleWidth(TASK_SUMMARY_ELLIPSIS);
+
+	if (keysOnly) {
+		const fragments = extractKeyFragments(oneLine);
+		if (fragments.length > 0) {
+			const keyMax = maxWidth - 1;
+			let keys = "";
+			for (const fragment of fragments) {
+				const piece = keys ? `${TASK_SUMMARY_KEY_SEP}${fragment}` : fragment;
+				const total = keys + piece;
+				if (visibleWidth(total) > keyMax) {
+					// Budget exhausted: keep what fits, unless nothing fits yet.
+					if (!keys) {
+						// A single over-long fragment keeps its tail
+						// (extension/symbol) and is prefixed with the ellipsis.
+						const fragmentSegments = [...graphemeSegmenter.segment(piece)].map((s) => s.segment);
+						keys = `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(fragmentSegments, keyMax - ellipsisWidth)}`;
+					}
+					break;
+				}
+				keys = total;
+			}
+			return keys;
+		}
+	}
+
+	// No distinctive fragments (or prose mode): fall back to head…tail.
+	const tailMax = Math.max(
+		TASK_SUMMARY_TAIL_MIN,
+		Math.min(TASK_SUMMARY_TAIL_MAX, Math.round(maxWidth * TASK_SUMMARY_TAIL_SHARE)),
+	);
+	const headMax = maxWidth - ellipsisWidth - tailMax;
+	if (headMax <= 0) {
+		return `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(segments, maxWidth - ellipsisWidth)}`;
+	}
+	return `${takeGraphemes(segments, headMax)}${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(segments, tailMax)}`;
 }
 
 function formatTokens(count: number): string {
@@ -199,8 +323,11 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.status = status;
-		if (status === "running" && run.startedAt === undefined) {
-			run.startedAt = Date.now();
+		if (status === "running") {
+			if (run.startedAt === undefined) run.startedAt = Date.now();
+			// A model-fallback retry after a failed attempt restarts the clock; a
+			// stale endedAt would freeze the elapsed display at the first attempt.
+			if (run.endedAt !== undefined) run.endedAt = undefined;
 		} else if ((status === "done" || status === "failed") && run.endedAt === undefined) {
 			run.endedAt = Date.now();
 		}
@@ -222,6 +349,19 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Set a widget note on the run (e.g. that its auto-fix chain is still running). */
+	setAnnotation(id: number, text: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.annotation = text;
+		this.notify();
+	}
+
+	/** Look up a run by id without removing it. */
+	findRun(id: number): RunView | undefined {
+		return this.find(id);
+	}
+
 	/** Remove a run (finished runs leave the widget). Returns the removed run. */
 	removeRun(id: number): RunView | undefined {
 		const index = this.runs.findIndex((r) => r.id === id);

package/src/spawn.ts

@@ -15,6 +15,7 @@ import { existsSync, mkdirSync, unlinkSync, rmdirSync, writeFileSync } from "nod
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig, AgentSource } from "./agents.ts";
@@ -134,7 +135,9 @@ export function writeResultArtifact(output: string, agentName: string): string {
 	const dir = join(tmpdir(), "pi-subagents-results");
 	mkdirSync(dir, { recursive: true });
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
-	const filePath = join(dir, `${Date.now()}-${safeName}.md`);
+	// A random suffix keeps same-millisecond writes from clobbering each other.
+	const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	const filePath = join(dir, `${unique}-${safeName}.md`);
 	writeFileSync(filePath, output, "utf8");
 	return filePath;
 }
@@ -457,8 +460,13 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			proc.stdin?.on("error", () => undefined);
 			proc.stdin?.end(`Task: ${task}`);
 
+			// Decode stdout through a StringDecoder so multi-byte UTF-8 characters
+			// (CJK, emoji) split across chunk boundaries never produce U+FFFD
+			// replacement characters — a corrupted JSON line would drop the whole
+			// message (including a reviewer's verdict line) from parsing.
+			const stdoutDecoder = new StringDecoder("utf8");
 			proc.stdout.on("data", (data) => {
-				buffer += data.toString();
+				buffer += stdoutDecoder.write(data);
 				const lines = buffer.split("\n");
 				buffer = lines.pop() || "";
 				for (const line of lines) processLine(line);
@@ -469,6 +477,9 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			});
 
 			proc.on("close", (code) => {
+				// Flush any bytes still held by the decoder (a trailing incomplete
+				// multi-byte sequence) before processing the final buffer.
+				buffer += stdoutDecoder.end();
 				if (buffer.trim()) processLine(buffer);
 				// A null exit code means the process was terminated by a signal and
 				// must be reported as failure, never as a false clean completion.