@ferris1225/pi-subagents 0.17.0 → 0.18.0

package/README.md

@@ -389,6 +389,13 @@ for `idleTimeoutSec` seconds) are treated as model-level failures and do trigger
 since a stalled SSE stream is usually a provider-side issue. Results carry a `model fell back
 from …` note when it happened.
 
+If the model is unavailable or broken and the fallback retry also fails (or no fallback model
+is available), the task is **handed back to the main window**: the completion message tells
+the main agent to execute the task itself with its own tools instead of leaving a dead
+failure. A background task that crashes with an exception (spawn infra, delivery API, ...)
+is never silently swallowed either — the user gets a `✗ … 派发失败` error notification and
+the failure is delivered to the main agent, which can re-dispatch it.
+
 Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
 
 ## Agent discovery and overrides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.17.0",
+  "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,
 	};
 }
 
@@ -140,6 +156,14 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number, 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)
@@ -393,6 +417,7 @@ export default function (pi: ExtensionAPI): void {
 						stderr: errorMessage,
 						stopReason: signal.aborted ? "aborted" : "error",
 						errorMessage,
+						dispatchFailed: true,
 					};
 				}
 			};
@@ -438,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, ctx.cwd),
-							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();
 					},
@@ -451,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 */
+						}
+					},
 				);
 			};
 
@@ -493,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;
@@ -516,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, ctx.cwd),
+							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.
@@ -533,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/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 {
@@ -158,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.