@ferris1225/pi-subagents 0.16.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.16.1",
+  "version": "0.18.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/background.ts

@@ -3,6 +3,10 @@
  *
  * Tasks get their own AbortSignal rather than inheriting the foreground agent
  * turn's signal. The owning extension cancels all work only on session teardown.
+ *
+ * Task exceptions are never swallowed: the per-task onError callback receives
+ * them (unless the task was cancelled) so callers can surface the failure to
+ * the user and the main agent instead of it vanishing into the queue.
  */
 
 export type BackgroundTask = (signal: AbortSignal) => Promise<void>;
@@ -11,6 +15,9 @@ interface PendingTask {
 	task: BackgroundTask;
 	controller: AbortController;
 	onCancelled?: () => void;
+	/** Invoked when the task throws and was not cancelled (cancellation is not a
+	 * failure — e.g. session shutdown races must never be reported as errors). */
+	onError?: (error: unknown) => void;
 }
 
 export class BackgroundTaskQueue {
@@ -33,15 +40,15 @@ export class BackgroundTaskQueue {
 		this.drain();
 	}
 
-	enqueue(task: BackgroundTask, onCancelled?: () => void): AbortController {
+	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void): AbortController {
 		const controller = new AbortController();
 		if (this.stopped) {
 			controller.abort();
-			onCancelled?.();
+			this.runCancelled(onCancelled);
 			return controller;
 		}
 
-		this.pending.push({ task, controller, onCancelled });
+		this.pending.push({ task, controller, onCancelled, onError });
 		this.drain();
 		return controller;
 	}
@@ -53,25 +60,47 @@ export class BackgroundTaskQueue {
 
 		for (const entry of this.pending.splice(0)) {
 			entry.controller.abort();
-			entry.onCancelled?.();
+			this.runCancelled(entry.onCancelled);
 		}
 		for (const controller of this.active) controller.abort();
 	}
 
+	/** Cancellation callbacks are user-supplied: a throw must never break the queue
+	 * (mirrors the try/catch around onError in drain). */
+	private runCancelled(callback: (() => void) | undefined): void {
+		if (!callback) return;
+		try {
+			callback();
+		} catch {
+			/* cancellation callbacks must never break the queue */
+		}
+	}
+
 	private drain(): void {
 		while (!this.stopped && this.active.size < this.concurrency) {
 			const entry = this.pending.shift();
 			if (!entry) return;
 			if (entry.controller.signal.aborted) {
-				entry.onCancelled?.();
+				this.runCancelled(entry.onCancelled);
 				continue;
 			}
 
 			this.active.add(entry.controller);
-			void entry.task(entry.controller.signal).catch(() => undefined).finally(() => {
-				this.active.delete(entry.controller);
-				this.drain();
-			});
+			void entry.task(entry.controller.signal)
+				.catch((error: unknown) => {
+					// Cancellation is not a failure: aborted work (e.g. session
+					// shutdown) must never be reported as an exception.
+					if (entry.controller.signal.aborted) return;
+					try {
+						entry.onError?.(error);
+					} catch {
+						/* error reporting must never break the queue */
+					}
+				})
+				.finally(() => {
+					this.active.delete(entry.controller);
+					this.drain();
+				});
 		}
 	}
 }

package/src/index.ts

@@ -32,6 +32,7 @@ import {
 	currentSubagentDepth,
 	getResultOutput,
 	isFailedResult,
+	isModelLevelFailure,
 	reviewVerdict,
 	runSingleAgentWithModelFallback,
 	truncateResultOutput,
@@ -92,6 +93,21 @@ function failedStartResult(agentName: string, task: string, errorMessage: string
 		stderr: errorMessage,
 		usage: emptyUsage(),
 		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+/** Failed result for a background task that crashed with an exception (spawn
+ * infra, delivery API, ...) instead of returning a normal result. */
+function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return {
+		...queuedResult(agent, task, thinking),
+		exitCode: 1,
+		stderr: errorMessage,
+		stopReason: "error",
+		errorMessage,
+		dispatchFailed: true,
 	};
 }
 
@@ -124,7 +140,7 @@ function formatUsage(usage: UsageStats): string {
 	return parts.join(" ");
 }
 
-function formatCompletionBlock(result: SingleResult, maxResultLines: number): string {
+function formatCompletionBlock(result: SingleResult, maxResultLines: number, cwd?: string): string {
 	const status = isFailedResult(result) ? "failed" : "completed";
 	const usage = formatUsage(result.usage);
 	const output = getResultOutput(result);
@@ -135,11 +151,19 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number): st
 	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)})`);
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent, cwd)})`);
 	}
 	return lines.join("\n");
 }
 
+/** Instruction appended to a model-level failure: the sub-agent's provider never
+ * produced usable output (or the run stalled), so the task is handed back to the
+ * main window instead of being left as a dead failure. */
+function modelLevelTakeoverNote(result: SingleResult): string {
+	const retry = result.modelFallbackFrom ? ", and the retry with the main-window model also failed" : "";
+	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${retry}. Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
+}
+
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
 	// Init-time decisions need the config synchronously; the full (migrating)
@@ -191,6 +215,9 @@ export default function (pi: ExtensionAPI): void {
 		sessionActive = false;
 		completionBatcher.dispose();
 		backgroundQueue.cancelAll();
+		// Clear the monitor so stale runs from this session never leak into the
+		// next one (the module-level singleton survives across sessions).
+		monitor.clear();
 	});
 
 	pi.registerTool({
@@ -212,6 +239,7 @@ export default function (pi: ExtensionAPI): void {
 			"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.",
+			"NEVER sleep, wait, poll, or call other tools alongside subagent — it ends the turn immediately. The main agent is auto-resumed when results arrive; manual waiting only blocks the turn and delays delivery.",
 		],
 		parameters: SubagentParams,
 
@@ -249,6 +277,7 @@ export default function (pi: ExtensionAPI): void {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
 				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
 				if (!run) return; // already finished — stay idempotent
+				if (opts?.retain) monitor.setRetained(runId, true);
 				if (opts?.silent || !sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
 				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
@@ -388,6 +417,7 @@ export default function (pi: ExtensionAPI): void {
 						stderr: errorMessage,
 						stopReason: signal.aborted ? "aborted" : "error",
 						errorMessage,
+						dispatchFailed: true,
 					};
 				}
 			};
@@ -433,11 +463,20 @@ export default function (pi: ExtensionAPI): void {
 						// success, a stuck one needs a human).
 						monitor.removeRun(parentRunId);
 						if (!sessionActive) return;
-						const items: CompletionMessageItem[] = chain.map((r) => ({
-							agent: r.agent,
-							block: formatCompletionBlock(r, config.maxResultLines),
-							triggerTurn: true,
-						}));
+						const items: CompletionMessageItem[] = chain.map((r) => {
+							// A model-level chain run (worker or re-review whose provider never
+							// produced output) is handed to the main window like any other
+							// sub-agent run: the block carries the takeover note. Dispatch
+							// crashes (dispatchFailed) are excluded by the gate itself.
+							const modelLevel = isFailedResult(r) && isModelLevelFailure(r);
+							return {
+								agent: r.agent,
+								block: modelLevel
+									? `${formatCompletionBlock(r, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(r)}`
+									: formatCompletionBlock(r, config.maxResultLines, ctx.cwd),
+								triggerTurn: true,
+							};
+						});
 						sendCompletionGroup(items);
 						completionBatcher.flush();
 					},
@@ -446,6 +485,30 @@ export default function (pi: ExtensionAPI): void {
 						// in-flight chain run was already finished by its launchInLoop path).
 						monitor.removeRun(parentRunId);
 					},
+					(error) => {
+						// A crash inside the chain orchestration (failed runs are caught by
+						// launchInLoop and delivered as part of the chain) must not vanish:
+						// drop the retained parent row, notify, and deliver a failed result
+						// so the main agent knows the chain never completed.
+						monitor.removeRun(parentRunId);
+						if (!sessionActive) return;
+						const errorMessage = error instanceof Error ? error.message : String(error);
+						try {
+							ctx.ui.notify(`✗ auto-fix chain 派发失败: ${errorMessage}`, "error");
+							// Keep the triggering review's findings: the chain crashed before any
+							// fix round ran, and the main agent needs the review to act on it.
+							sendCompletionGroup([
+								{
+									agent: initialReviewerResult.agent,
+									block: `${formatCompletionBlock(initialReviewerResult, config.maxResultLines, ctx.cwd)}\n\nAuto-fix chain crashed before completion: ${errorMessage}. The planned fix rounds did not run; the review above is the triggering reviewer's full output.`,
+									triggerTurn: true,
+								},
+							]);
+							completionBatcher.flush();
+						} catch {
+							/* a second delivery failure must not throw through the queue */
+						}
+					},
 				);
 			};
 
@@ -488,8 +551,11 @@ export default function (pi: ExtensionAPI): void {
 								stderr: errorMessage,
 								stopReason: backgroundSignal.aborted ? "aborted" : "error",
 								errorMessage,
+								dispatchFailed: true,
 							};
-							finishRun(runId, "failed");
+							// The dedicated 派发失败 notification below replaces the generic
+							// failure toast for dispatch crashes, so finish silently here.
+							finishRun(runId, "failed", { silent: true });
 						}
 
 						if (!sessionActive) return;
@@ -511,13 +577,31 @@ export default function (pi: ExtensionAPI): void {
 							return;
 						}
 						const failed = isFailedResult(result);
-						finishRun(runId, failed ? "failed" : "done");
+						// Model-level failures and dispatch crashes get their own dedicated
+						// 派发失败 notification below, so finishRun's generic failure toast is
+						// silenced for them (computed before finishRun for that reason).
+						const modelLevel = failed && isModelLevelFailure(result);
+						const dispatchFailed = result.dispatchFailed === true;
+						finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
 						if (!sessionActive) return;
+						// Model-level failure: the configured model is unavailable or broke
+						// and the retry with the main-window model (when distinct) also
+						// failed. Instead of leaving a dead failure, hand the task to the
+						// main window — the main agent executes it itself with its own tools.
 						const completion: CompletionMessageItem = {
 							agent: result.agent,
-							block: formatCompletionBlock(result, config.maxResultLines),
+							block: modelLevel
+								? `${formatCompletionBlock(result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(result)}`
+								: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
 							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
 						};
+						if (modelLevel) {
+							ctx.ui.notify(`✗ ${result.agent} 派发失败: 模型不可用或出错，任务已交由主窗口执行`, "error");
+						} else if (dispatchFailed) {
+							// An exception inside the dispatch layer (spawn infra, temp-file/fs
+							// errors, ...): the main agent must know so it can re-dispatch.
+							ctx.ui.notify(`✗ ${result.agent} 派发失败: ${result.errorMessage ?? "dispatch crashed"}`, "error");
+						}
 						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.
@@ -528,6 +612,28 @@ export default function (pi: ExtensionAPI): void {
 						}
 					},
 					() => finishRun(runId, "failed"),
+					(error) => {
+						// The task body converts sub-agent failures into delivered results; an
+						// exception escaping it (spawn infra, delivery API, ...) must not
+						// vanish: notify the user and deliver a failed result so the main
+						// agent knows the dispatch failed and can re-dispatch.
+						const crashed = dispatchFailedResult(agent, task, error, thinkingLevel);
+						finishRun(runId, "failed", { silent: true });
+						if (!sessionActive) return;
+						try {
+							ctx.ui.notify(`✗ ${agent.name} 派发失败: ${crashed.errorMessage}`, "error");
+							sendCompletionGroup([
+								{
+									agent: agent.name,
+									block: formatCompletionBlock(crashed, config.maxResultLines, ctx.cwd),
+									triggerTurn: true,
+								},
+							]);
+							completionBatcher.flush();
+						} catch {
+							/* a second delivery failure must not throw through the queue */
+						}
+					},
 				);
 
 				return pending;

package/src/monitor.ts

@@ -42,6 +42,10 @@ export interface RunView {
 	relationLabel?: string;
 	/** Free-form note shown in the widget next to the status label (e.g. "auto-fix chain running"). */
 	annotation?: string;
+	/** True when a finished run is intentionally kept in the widget (e.g. an
+	 * auto-fix chain parent whose chain is still running). beginTurn preserves
+	 * retained runs so they are not swept between turns. */
+	retained?: boolean;
 }
 
 /** Optional chain metadata for runs spawned by an auto-fix loop. */
@@ -298,7 +302,12 @@ export class MonitorStore {
 	beginTurn(): void {
 		// Clear finished runs from a previous turn, but keep any still-active
 		// (queued/running) ones so a concurrent sub-agent call is not wiped.
-		this.runs = this.runs.filter((r) => r.status === "queued" || r.status === "running");
+		// Retained runs (e.g. an auto-fix chain parent whose chain is still
+		// running) are also preserved — their status is "done" but they must
+		// stay visible until the chain resolves.
+		this.runs = this.runs.filter(
+			(r) => r.status === "queued" || r.status === "running" || r.retained,
+		);
 		this.notify();
 	}
 
@@ -357,11 +366,27 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Mark a run as retained (kept in the widget despite being finished). */
+	setRetained(id: number, retained: boolean): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.retained = retained;
+		this.notify();
+	}
+
 	/** Look up a run by id without removing it. */
 	findRun(id: number): RunView | undefined {
 		return this.find(id);
 	}
 
+	/** Remove all runs (used on session shutdown so stale state never leaks
+	 * into the next session). Does not reset the id counter so in-flight
+	 * finishRun calls from the old session remain safe no-ops. */
+	clear(): void {
+		this.runs = [];
+		this.notify();
+	}
+
 	/** 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/prompt.ts

@@ -41,6 +41,10 @@ It immediately ends the current main-agent turn so the user can keep working. Wh
 finishes, its result is sent back as a message that automatically resumes the main agent;
 if the main agent is busy, the result waits as a follow-up.
 
+NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout) to wait for
+a sub-agent — the turn already ended and the main agent is auto-resumed when results arrive.
+Manual waiting blocks the turn, delays result delivery, and wastes the user's time.
+
 Available agents:
 ${catalog}
 

package/src/spawn.ts

@@ -57,6 +57,10 @@ export interface SingleResult {
 	errorMessage?: string;
 	/** Model the run degraded from: set when a failed run was retried with the main-window model. */
 	modelFallbackFrom?: string;
+	/** True when the result was synthesized from a thrown exception (spawn infra,
+	 * temp-file/fs errors, delivery bugs) instead of being produced by the agent
+	 * process. A dispatch failure is never a model-level failure. */
+	dispatchFailed?: boolean;
 }
 
 export interface SubagentDetails {
@@ -128,9 +132,14 @@ export function truncateResultOutput(output: string, maxLines: number): Truncate
 	return { text: kept.join("\n"), truncated: true };
 }
 
-/** Persist the full result where the main agent can read it on demand. Returns the file path. */
-export function writeResultArtifact(output: string, agentName: string): string {
-	const dir = join(tmpdir(), "pi-subagents-results");
+/** Persist the full result where the main agent can read it on demand. Returns the file path.
+ * Results are grouped under a per-project subdirectory so concurrent projects don't
+ * litter a single flat folder. */
+export function writeResultArtifact(output: string, agentName: string, cwd?: string): string {
+	const projectSlug = cwd
+		? basename(cwd).replace(/[^\w.-]+/g, "_") || "default"
+		: "default";
+	const dir = join(tmpdir(), "pi-subagents-results", projectSlug);
 	mkdirSync(dir, { recursive: true });
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	// A random suffix keeps same-millisecond writes from clobbering each other.
@@ -153,6 +162,10 @@ export function isFailedResult(result: SingleResult): boolean {
 export function isModelLevelFailure(result: SingleResult): boolean {
 	if (!isFailedResult(result)) return false;
 	if (result.stopReason === "aborted") return false;
+	// A result synthesized from a thrown exception (spawn infra, fs, delivery
+	// bugs) never came from the provider: it is a dispatch failure, not a
+	// model-level one, and must not be handed back as a model problem.
+	if (result.dispatchFailed) return false;
 	// An idle timeout (stdout went silent) signals a stalled provider connection,
 	// not a task-level failure: allow model fallback even if the model produced
 	// partial output before going quiet.
@@ -166,7 +179,10 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 
 export function getResultOutput(result: SingleResult): string {
 	if (isFailedResult(result)) {
-		return result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+		const error = result.errorMessage || result.stderr;
+		const partial = getFinalOutput(result.messages);
+		if (error && partial) return `${error}\n\n--- Partial output ---\n${partial}`;
+		return error || partial || "(no output)";
 	}
 	return getFinalOutput(result.messages) || "(no output)";
 }
@@ -506,12 +522,13 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 
 		currentResult.exitCode = exitCode;
 		if (wasAborted) {
+			currentResult.stopReason = "aborted";
+			currentResult.errorMessage ??= "Subagent was aborted";
 			if (onLive) {
 				try {
 					onLive({ kind: "status", status: "failed" });
 				} catch { /* never throw from event handling */ }
 			}
-			throw new Error("Subagent was aborted");
 		}
 		return currentResult;
 	} finally {