@ferris1225/pi-subagents 0.15.0 → 0.16.1

package/README.md

@@ -23,10 +23,13 @@ agent, and keep the workflow moving without manual polling.
   elapsed time; completion also produces a concise notification.
 - **Per-agent configuration** — enable agents, pick model and thinking strength per agent,
   tune concurrency limits, and choose discovery scope from `/subagents-setup`.
+- **Idle watchdog** — a sub-agent whose stdout goes silent for a configurable
+  duration is terminated and retried with the fallback model, so a stalled SSE
+  stream never hangs the workflow.
 - **Automatic model fallback** — if an agent's model fails at the provider level before
-  producing any output, the run is retried once with the main window's current model.
-  Per-run only, never persisted: a transient provider hiccup does not silently downgrade
-  the configured model.
+  producing any output (or the idle watchdog fires), the run is retried once with the
+  main window's current model. Per-run only, never persisted: a transient provider
+  hiccup does not silently downgrade the configured model.
 - **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
   recurse.
 
@@ -331,7 +334,8 @@ agent's default — its frontmatter `thinking`, else the global default). The gl
   "proactiveInjection": true,
   "agentScope": "user",
   "maxConcurrency": 4,
-  "maxFixRounds": 2
+  "maxFixRounds": 2,
+  "idleTimeoutSec": 90
 }
 ```
 
@@ -347,6 +351,7 @@ agent's default — its frontmatter `thinking`, else the global default). The gl
 | `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
 | `maxConcurrency` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
 | `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL`: the extension dispatches a `worker` (briefed with the review's concrete findings) then a `reviewer` re-review, repeating up to this many times before waking the main agent with the full chain. `0` disables it (the main agent handles fixes itself). Default 2. The reviewer stays read-only and in its own context; the loop is orchestrated by the extension, not by the reviewer. |
+| `idleTimeoutSec` | Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes silent for this long is terminated and retried with the fallback model (if one is available). `0` disables the idle watchdog. Default 90. This only fires when the child produces no output at all — a long but active run is never interrupted. |
 
 ### Configuration migration
 
@@ -361,6 +366,8 @@ The config file migrates itself on load — no manual steps after an upgrade:
 - **Removed keys** — `maxSubagentDepth` (0.14) is dropped on load: sub-agent children are
   always leaf processes (the `subagent` tool is excluded from their toolset, with a depth
   marker as defense in depth). To disable delegation entirely, use `"enabledAgents": []`.
+- **New fields** — `idleTimeoutSec` (0.16) is filled in on load with its default (90)
+  when missing from an older config.
 
 Model selection uses this precedence:
 
@@ -375,7 +382,9 @@ At runtime, if an agent's model fails at the provider level before producing any
 model id, auth, thinking level, quota, ...), the run is retried **once** with the main window's
 current model. This per-run degradation is never persisted — a transient provider hiccup must
 not silently downgrade the configured model — and it does not apply to task-level failures
-(the model worked, the task failed), aborts, or timeouts. Results carry a `model fell back
+(the model worked, the task failed) or aborts. Idle timeouts (the child's stdout goes silent
+for `idleTimeoutSec` seconds) are treated as model-level failures and do trigger the fallback,
+since a stalled SSE stream is usually a provider-side issue. Results carry a `model fell back
 from …` note when it happened.
 
 Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.

package/package.json

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

@@ -58,6 +58,15 @@ export const DEFAULT_MAX_FIX_ROUNDS = 2;
 /** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
 export const MAX_FIX_ROUNDS_LIMIT = 5;
 
+/**
+ * Default idle timeout in seconds: a sub-agent whose stdout (JSON event stream)
+ * goes silent for this long is terminated and may be retried with the fallback
+ * model. 0 disables the idle watchdog. Default: 90.
+ */
+export const DEFAULT_IDLE_TIMEOUT_SEC = 90;
+/** Upper bound accepted for idleTimeoutSec (defensive clamp). 0 disables. */
+export const IDLE_TIMEOUT_SEC_LIMIT = 600;
+
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
 	enabledAgents: string[];
@@ -93,6 +102,12 @@ export interface SubagentsConfig {
 	 * Default: 2.
 	 */
 	maxFixRounds: number;
+	/**
+	 * Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes
+	 * silent for this long is terminated and may be retried with the fallback
+	 * model. 0 disables the idle watchdog. Default: 90.
+	 */
+	idleTimeoutSec: number;
 }
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
@@ -106,6 +121,7 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	agentScope: "user",
 	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
 	maxFixRounds: DEFAULT_MAX_FIX_ROUNDS,
+	idleTimeoutSec: DEFAULT_IDLE_TIMEOUT_SEC,
 };
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
@@ -151,6 +167,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		agentScope: DEFAULT_CONFIG.agentScope,
 		maxConcurrency: DEFAULT_CONFIG.maxConcurrency,
 		maxFixRounds: DEFAULT_CONFIG.maxFixRounds,
+		idleTimeoutSec: DEFAULT_CONFIG.idleTimeoutSec,
 	};
 
 	if (Array.isArray(raw.enabledAgents)) {
@@ -218,6 +235,11 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.maxFixRounds = Math.max(0, Math.min(MAX_FIX_ROUNDS_LIMIT, Math.round(raw.maxFixRounds)));
 	}
 
+	// 0 disables the idle watchdog; otherwise clamp to [0, upper].
+	if (typeof raw.idleTimeoutSec === "number" && Number.isFinite(raw.idleTimeoutSec)) {
+		config.idleTimeoutSec = Math.max(0, Math.min(IDLE_TIMEOUT_SEC_LIMIT, Math.round(raw.idleTimeoutSec)));
+	}
+
 	return config;
 }
 

package/src/index.ts

@@ -12,7 +12,6 @@
  * runaway recursion and keeps child context windows clean.
  */
 
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -31,7 +30,6 @@ import { buildDelegationDirective } from "./prompt.ts";
 import { runSetup } from "./setup.ts";
 import {
 	currentSubagentDepth,
-	getFinalOutput,
 	getResultOutput,
 	isFailedResult,
 	reviewVerdict,
@@ -217,7 +215,7 @@ export default function (pi: ExtensionAPI): void {
 		],
 		parameters: SubagentParams,
 
-		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			monitor.beginTurn();
 			let config = await loadConfig(configPath);
 			// Pick up concurrency changes from /subagents-setup without a restart.
@@ -375,6 +373,7 @@ export default function (pi: ExtensionAPI): void {
 							signal,
 							onLive,
 							makeDetails: makeDetails("single", true),
+							idleTimeoutMs: config.idleTimeoutSec * 1000,
 						},
 						sessionRef,
 					);
@@ -477,6 +476,7 @@ export default function (pi: ExtensionAPI): void {
 									signal: backgroundSignal,
 									onLive,
 									makeDetails: makeDetails("single", true),
+									idleTimeoutMs: config.idleTimeoutSec * 1000,
 								},
 								sessionRef,
 							);

package/src/setup.ts

@@ -14,6 +14,7 @@ import {
 	BUILTIN_AGENT_NAMES,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
+	DEFAULT_IDLE_TIMEOUT_SEC,
 	DEFAULT_MAX_CONCURRENCY,
 	DEFAULT_MAX_FIX_ROUNDS,
 	THINKING_LEVEL_VALUES,
@@ -197,6 +198,8 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 const CONCURRENCY_STEPS = [1, 2, 3, 4, 6, 8, 12, 16];
 /** Preset rounds offered for the auto-fix loop (0 disables it). */
 const FIX_ROUNDS_STEPS = [0, 1, 2, 3, 5];
+/** Preset seconds offered for the idle timeout (0 disables it). */
+const IDLE_TIMEOUT_STEPS = [0, 30, 60, 90, 120, 180, 300, 600];
 
 async function pickCount(
 	ctx: ExtensionCommandContext,
@@ -298,6 +301,15 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		);
 		if (maxFixRounds === undefined) return notifyCancelled(ctx);
 
+		const idleTimeoutSec = await pickCount(
+			ctx,
+			"Idle timeout in seconds? (0 = disabled, kills a sub-agent whose output goes silent)",
+			IDLE_TIMEOUT_STEPS,
+			base.idleTimeoutSec,
+			DEFAULT_IDLE_TIMEOUT_SEC,
+		);
+		if (idleTimeoutSec === undefined) return notifyCancelled(ctx);
+
 		const next: SubagentsConfig = {
 		enabledAgents: enabled,
 		agentModels: repairStaleModels(ctx, picked.models),
@@ -309,6 +321,7 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		agentScope: scope,
 		maxConcurrency,
 		maxFixRounds,
+		idleTimeoutSec,
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
@@ -323,6 +336,7 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		"Change agent scope",
 		"Change max concurrent sub-agents",
 		"Change max fix rounds",
+		"Change idle timeout",
 		"Full re-setup",
 	]);
 	if (choice === undefined) return notifyCancelled(ctx);
@@ -384,6 +398,16 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		);
 		if (maxFixRounds === undefined) return notifyCancelled(ctx);
 		next.maxFixRounds = maxFixRounds;
+	} else if (choice.startsWith("Change idle")) {
+		const idleTimeoutSec = await pickCount(
+			ctx,
+			"Idle timeout in seconds? (0 = disabled, kills a sub-agent whose output goes silent)",
+			IDLE_TIMEOUT_STEPS,
+			config.idleTimeoutSec,
+			DEFAULT_IDLE_TIMEOUT_SEC,
+		);
+		if (idleTimeoutSec === undefined) return notifyCancelled(ctx);
+		next.idleTimeoutSec = idleTimeoutSec;
 	}
 
 	await saveConfig(next, configPath);

package/src/spawn.ts

@@ -4,8 +4,7 @@
  * written to a temp file and passed via `--append-system-prompt` (which accepts a
  * file path). The task itself is sent through the child's stdin pipe, not another
  * temp file or command-line argument. Child stdout is a JSON-lines event stream;
- * we accumulate assistant messages from `message_end` events and stream partial
- * output back via onUpdate.
+ * we accumulate assistant messages from `message_end` events.
  *
  * Adapted from the official pi example `examples/extensions/subagent`.
  */
@@ -16,7 +15,6 @@ 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";
 import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
@@ -28,9 +26,11 @@ import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
 /** Default thinking level for sub-agents. pi clamps it to the resolved model's support. */
 export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
-/** No default deadline: sub-agents may run until completion or explicit cancellation. */
-export const SUBAGENT_TIMEOUT_MS = 0;
 export const SUBAGENT_KILL_GRACE_MS = 5_000;
+/** Default idle watchdog: terminate a child whose stdout goes silent for this
+ * many milliseconds. 0 disables it. The actual value comes from config
+ * (idleTimeoutSec); this constant is only a fallback for tests. */
+export const SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS = 0;
 
 export interface UsageStats {
 	input: number;
@@ -66,8 +66,6 @@ export interface SubagentDetails {
 	background?: boolean;
 }
 
-export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
-
 export type SubagentLiveEvent =
 	| { kind: "status"; status: "queued" | "running" | "done" | "failed" }
 	| { kind: "usage"; usage: UsageStats; model?: string }
@@ -155,9 +153,12 @@ export function isFailedResult(result: SingleResult): boolean {
 export function isModelLevelFailure(result: SingleResult): boolean {
 	if (!isFailedResult(result)) return false;
 	if (result.stopReason === "aborted") 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.
+	if (result.errorMessage?.includes("idle timeout")) return true;
 	// The model produced text: the failure belongs to the task, not the model.
 	if (getFinalOutput(result.messages)) return false;
-	if (result.errorMessage?.includes("timed out")) return false;
 	// Require evidence the failure came from the model/provider (an error
 	// message or stderr), not from the child process failing to start.
 	return result.messages.length > 0 || result.stderr.trim().length > 0;
@@ -170,26 +171,6 @@ export function getResultOutput(result: SingleResult): string {
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
-export async function mapWithConcurrencyLimit<TIn, TOut>(
-	items: TIn[],
-	concurrency: number,
-	fn: (item: TIn, index: number) => Promise<TOut>,
-): Promise<TOut[]> {
-	if (items.length === 0) return [];
-	const limit = Math.max(1, Math.min(concurrency, items.length));
-	const results: TOut[] = new Array(items.length);
-	let nextIndex = 0;
-	const workers = new Array(limit).fill(null).map(async () => {
-		while (true) {
-			const current = nextIndex++;
-			if (current >= items.length) return;
-			results[current] = await fn(items[current], current);
-		}
-	});
-	await Promise.all(workers);
-	return results;
-}
-
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
 	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
@@ -253,10 +234,10 @@ export interface RunSingleOptions {
 	cwd?: string;
 	/** Thinking level passed to the child pi process. */
 	thinkingLevel?: ThinkingLevel;
-	/** Optional timeout; zero (the default) disables it. Intended for tests and controlled callers. */
-	timeoutMs?: number;
+	/** Idle timeout in ms: terminate the child if its stdout produces no activity
+	 * for this duration. 0 (the default) disables the idle watchdog. */
+	idleTimeoutMs?: number;
 	signal?: AbortSignal;
-	onUpdate?: OnUpdateCallback;
 	onLive?: (e: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
 	env?: NodeJS.ProcessEnv;
@@ -270,9 +251,8 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		task,
 		cwd,
 		thinkingLevel = SUBAGENT_THINKING_LEVEL,
-		timeoutMs = SUBAGENT_TIMEOUT_MS,
+		idleTimeoutMs = SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS,
 		signal,
-		onUpdate,
 		onLive,
 		makeDetails,
 	} = options;
@@ -312,13 +292,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		thinking: thinkingLevel,
 	};
 
-	const emitUpdate = (): void => {
-		onUpdate?.({
-			content: [{ type: "text", text: getFinalOutput(currentResult.messages) || "(running...)" }],
-			details: makeDetails([currentResult]),
-		});
-	};
-
 	try {
 		if (agent.systemPrompt.trim()) {
 			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
@@ -328,7 +301,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		}
 
 		let wasAborted = false;
-		let timedOut = false;
 
 		// Increment depth so nested sub-agents can be guarded against runaway recursion.
 		const childDepth = currentSubagentDepth(options.env) + 1;
@@ -349,14 +321,15 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			let closed = false;
 			let termSent = false;
 			let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
-			let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 			let abortHandler: (() => void) | undefined;
+			let lastActivityAt = Date.now();
+			let idleTimer: ReturnType<typeof setInterval> | undefined;
 
 			const finish = (code: number | null): void => {
 				if (closed) return;
 				closed = true;
 				if (forceKillTimer) clearTimeout(forceKillTimer);
-				if (timeoutTimer) clearTimeout(timeoutTimer);
+				if (idleTimer) clearInterval(idleTimer);
 				if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
 				resolve(code ?? 1);
 			};
@@ -446,12 +419,10 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 							onLive({ kind: "usage", usage: { ...currentResult.usage }, model: currentResult.model });
 						} catch { /* never throw from event handling */ }
 					}
-					emitUpdate();
 				}
 
 				if (event.type === "tool_result_end" && event.message) {
 					currentResult.messages.push(event.message as Message);
-					emitUpdate();
 				}
 			};
 			// Send the task through the child stdin pipe instead of the process
@@ -466,6 +437,7 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			// message (including a reviewer's verdict line) from parsing.
 			const stdoutDecoder = new StringDecoder("utf8");
 			proc.stdout.on("data", (data) => {
+				lastActivityAt = Date.now();
 				buffer += stdoutDecoder.write(data);
 				const lines = buffer.split("\n");
 				buffer = lines.pop() || "";
@@ -486,7 +458,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 				const failed =
 					code !== 0 ||
 					wasAborted ||
-					timedOut ||
 					(signal?.aborted ?? false) ||
 					currentResult.stopReason === "error" ||
 					currentResult.stopReason === "aborted";
@@ -510,13 +481,17 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 				finish(1);
 			});
 
-			if (timeoutMs > 0) {
-				timeoutTimer = setTimeout(() => {
-					timedOut = true;
-					currentResult.stopReason = "error";
-					currentResult.errorMessage = `Subagent timed out after ${Math.ceil(timeoutMs / 1000)} seconds.`;
-					terminate();
-				}, timeoutMs);
+			if (idleTimeoutMs > 0) {
+				const checkInterval = Math.min(10_000, Math.floor(idleTimeoutMs / 3));
+				idleTimer = setInterval(() => {
+					if (closed) return;
+					if (Date.now() - lastActivityAt >= idleTimeoutMs) {
+						if (idleTimer) clearInterval(idleTimer);
+						currentResult.stopReason = "error";
+						currentResult.errorMessage = `Subagent idle timeout: no activity for ${Math.ceil(idleTimeoutMs / 1000)} seconds.`;
+						terminate();
+					}
+				}, checkInterval);
 			}
 
 			if (signal) {