@ferris1225/pi-subagents 2.0.1 → 2.0.3

package/README.md

@@ -88,9 +88,10 @@ index.
 - **Direct fallback with real thinking capabilities** — each agent has at most
   one selected model. An unavailable selection, rate limit, invalid key, quota,
   missing model, or provider failure hands directly to the current main model.
-  A child-only provider adapter forces request retries to zero, and the RPC
-  parent cancels Pi's outer turn retry before another call, without changing user
-  settings. Auto thinking clamps the agent preference to the
+  A child-only provider adapter forces inner request retries to zero; transient
+  stream drops still use Pi's outer turn retry, and only a settled model-level
+  failure hands off, without changing user settings. Auto thinking clamps the
+  agent preference to the
   effective model's real `thinkingLevelMap`; manual setup shows only levels that
   model supports.
 - **Resumes, retargets, and forks preserve context** — every run is session-backed.
@@ -331,14 +332,19 @@ available catalog is skipped. Any model-level runtime failure — rate limit,
 quota, invalid key/auth, missing model, provider error, or idle model stream —
 hands directly to current main, including stream errors that retain partial text.
 A child-only Pi extension wraps the selected provider's registered API stream
-with `maxRetries: 0`; if Pi schedules its separate outer turn retry, the RPC parent
-immediately sends `abort_retry` before another provider call. This uses supported
-extension/RPC surfaces in Node and standalone/Bun builds, never rewrites global or
-project settings, and does not alter descendant tool environments. Tool/test
-failures stay on the same model because they are task failures, not model
-availability failures. Only a truly
-zero-activity process startup race can retry; an accepted prompt or any
-agent/turn/stream/tool activity forbids replay.
+with `maxRetries: 0` so a deterministic auth/quota miss fails fast. Transient
+stream drops such as xAI `terminated` still use Pi's outer turn retry — the
+parent does not `abort_retry` them — and only a settled model-level failure
+hands off to current main. This uses supported extension/RPC surfaces in Node
+and standalone/Bun builds, never rewrites global or project settings, and does
+not alter descendant tool environments. Tool/test failures stay on the same
+model because they are task failures, not model availability failures. A child is
+probed with RPC `get_state` before the first prompt so the 30s command ACK clock
+does not include process boot. Only a zero-activity startup miss can retry — a
+silent fast exit, a `get_state` handshake timeout, or an initial prompt ACK
+timeout before any agent/turn/stream/tool activity. Those transport misses are
+not model-level failures and do not hand the task to the main window. An accepted
+prompt or any activity forbids replay.
 
 Auto thinking starts from the Agent's declared preference (`low` for `explore`,
 `high` for the other built-ins) and uses Pi's capability map to clamp it to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Controllable background sub-agent threads for pi: specialized roles, capability-aware thinking, direct main-model fallback, auto-fix chains, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/dispatch.ts

@@ -1483,7 +1483,8 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
 							};
 							if (modelLevel) {
-								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: model unavailable or broken — task handed to the main window`, "error");
+								const detail = result.errorMessage?.trim() || "model unavailable or broken";
+								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${detail} — task handed to the main window`, "error");
 							} else if (dispatchFailed) {
 								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
 							}

package/src/format.ts

@@ -155,11 +155,15 @@ export function formatCompletionBlock(
  * fresh (which would re-scan everything). */
 export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
 	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
+	const detail = result.errorMessage?.trim();
+	const cause = detail
+		? `its model/provider call failed (${detail})`
+		: "its model was unavailable or failed (or the run stalled)";
 	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
 	const recovery = sessionPreserved
 		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
 		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
-	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${retry}.${recovery}`;
+	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
 }
 
 /** Resolve a run-id request to actual ids: an exact numeric match always wins

package/src/rpc-run.ts

@@ -20,9 +20,16 @@ import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 export const SUBAGENT_KILL_GRACE_MS = 5_000;
+/** ACK budget after the child is known to be reading RPC. */
 export const RPC_COMMAND_TIMEOUT_MS = 30_000;
+/** Time allowed for the child to boot and answer get_state. */
+export const RPC_READY_TIMEOUT_MS = 60_000;
 export const RPC_ABORT_SETTLE_TIMEOUT_MS = 5_000;
 
+export function isRpcCommandTimeoutError(message?: string): boolean {
+	return typeof message === "string" && message.includes("Timed out waiting for RPC response");
+}
+
 /** Prevent RPC prompt expansion when a control objective itself starts with
  * slash (for example `/subagents-setup`). The original text stays verbatim
  * below a non-command prefix and therefore always starts a model turn. */
@@ -59,6 +66,9 @@ export interface RpcSingleResult {
 	 * model execution. This remains main-model handoff eligible even when an
 	 * earlier, aborted objective left assistant text in the session. */
 	rpcPromptRejected?: boolean;
+	/** Handshake or initial prompt ACK never came back. This is a startup/
+	 * transport miss, not a model/provider failure. */
+	rpcStartupFailed?: boolean;
 	/** The child accepted a prompt; startup retries must never duplicate it. */
 	rpcPromptAccepted?: boolean;
 	/** Pi emitted agent/turn/model/tool activity for this attempt. */
@@ -408,7 +418,7 @@ interface RpcResponse {
 interface PendingRequest {
 	resolve: (response: RpcResponse) => void;
 	reject: (error: Error) => void;
-	timer: ReturnType<typeof setTimeout>;
+	timer?: ReturnType<typeof setTimeout>;
 }
 
 interface Deferred<T> {
@@ -442,6 +452,8 @@ export interface RunRpcAttemptOptions {
 	onLive?: (event: SubagentLiveEvent) => void;
 	env?: NodeJS.ProcessEnv;
 	control?: RpcRunControl;
+	rpcReadyTimeoutMs?: number;
+	rpcCommandTimeoutMs?: number;
 }
 
 /** Run one persistent RPC child until a stable `agent_settled` or control action. */
@@ -549,7 +561,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 
 	const rejectPending = (error: Error): void => {
 		for (const request of pendingRequests.values()) {
-			clearTimeout(request.timer);
+			if (request.timer) clearTimeout(request.timer);
 			request.reject(error);
 		}
 		pendingRequests.clear();
@@ -589,32 +601,46 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 		}
 	};
 
-	const writeLine = (value: object): void => {
-		if (!proc.stdin || proc.stdin.destroyed || !proc.stdin.writable) {
-			throw new Error("Subagent RPC stdin is not writable.");
-		}
-		// JSON strings may contain U+2028/U+2029. Only the final ASCII LF frames a
-		// record; never use a generic line reader on the receiving side.
-		proc.stdin.write(`${JSON.stringify(value)}\n`, "utf8");
-	};
+	const readyTimeoutMs = options.rpcReadyTimeoutMs ?? RPC_READY_TIMEOUT_MS;
+	const commandTimeoutMs = options.rpcCommandTimeoutMs ?? RPC_COMMAND_TIMEOUT_MS;
 
-	const send = async (command: Record<string, unknown>): Promise<RpcResponse> => {
+	const writeLine = (value: object): Promise<void> =>
+		new Promise((resolve, reject) => {
+			if (!proc.stdin || proc.stdin.destroyed || !proc.stdin.writable) {
+				reject(new Error("Subagent RPC stdin is not writable."));
+				return;
+			}
+			// JSON strings may contain U+2028/U+2029. Only the final ASCII LF frames a
+			// record; never use a generic line reader on the receiving side.
+			proc.stdin.write(`${JSON.stringify(value)}\n`, "utf8", (error) => {
+				if (error) reject(error);
+				else resolve();
+			});
+		});
+
+	const send = async (command: Record<string, unknown>, timeoutMs = commandTimeoutMs): Promise<RpcResponse> => {
 		if (finished || closed) throw new Error("Subagent RPC process is no longer active.");
 		const id = `req_${++requestId}`;
+		const payload = { ...command, id };
 		return new Promise<RpcResponse>((resolve, reject) => {
-			const timer = setTimeout(() => {
-				pendingRequests.delete(id);
-				reject(new Error(`Timed out waiting for RPC response to ${String(command.type)}.`));
-			}, RPC_COMMAND_TIMEOUT_MS);
-			if (typeof timer.unref === "function") timer.unref();
-			pendingRequests.set(id, { resolve, reject, timer });
-			try {
-				writeLine({ ...command, id });
-			} catch (error) {
-				pendingRequests.delete(id);
-				clearTimeout(timer);
-				reject(error instanceof Error ? error : new Error(String(error)));
-			}
+			const pending: PendingRequest = { resolve, reject };
+			pendingRequests.set(id, pending);
+			void writeLine(payload).then(
+				() => {
+					if (!pendingRequests.has(id)) return;
+					pending.timer = setTimeout(() => {
+						pendingRequests.delete(id);
+						reject(new Error(`Timed out waiting for RPC response to ${String(command.type)}.`));
+					}, timeoutMs);
+					if (typeof pending.timer.unref === "function") pending.timer.unref();
+				},
+				(error) => {
+					if (!pendingRequests.has(id)) return;
+					pendingRequests.delete(id);
+					if (pending.timer) clearTimeout(pending.timer);
+					reject(error instanceof Error ? error : new Error(String(error)));
+				},
+			);
 		}).then((response) => {
 			if (!response.success) throw new Error(response.error || `RPC ${response.command} failed.`);
 			return response;
@@ -708,7 +734,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				result.exitCode = 1;
 				result.stopReason = "error";
 				result.errorMessage = `Replacement prompt was rejected: ${promptError.message}`;
-				result.rpcPromptRejected = true;
+				if (!isRpcCommandTimeoutError(promptError.message)) result.rpcPromptRejected = true;
 				finish();
 				terminate();
 				if (!closed) await processClosed.promise;
@@ -716,18 +742,41 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			}
 		},
 		async park(): Promise<void> {
+			const markParked = (): void => {
+				result.parked = true;
+				result.exitCode = 0;
+				result.stopReason = undefined;
+				result.errorMessage = undefined;
+				result.rpcStartupFailed = undefined;
+				result.rpcPromptRejected = undefined;
+			};
 			if (finished) {
 				if (!closed) await processClosed.promise;
+				if (result.parked) return;
+				// Handshake/startup already tore the child down. Convert a pre-prompt
+				// settlement into a park instead of throwing past the control tool.
+				if (!result.rpcPromptAccepted) {
+					markParked();
+					return;
+				}
 				throw new Error("Thread already settled before it could be parked.");
 			}
 			setAttemptPhase("interrupting");
+			if (!initialPromptResolved) {
+				const parked = new Error("Run was parked before its initial prompt.");
+				resolveInitialPrompt(false, parked);
+				rejectPending(parked);
+				markParked();
+				setAttemptPhase("parked");
+				finish();
+				terminate();
+				if (!closed) await processClosed.promise;
+				return;
+			}
 			const accepted = await abortAcceptedPrompt();
 			if (!accepted && !closed) await processClosed.promise;
 			if (finished && accepted) throw new Error("Thread exited while parking.");
-			result.parked = true;
-			result.exitCode = 0;
-			result.stopReason = undefined;
-			result.errorMessage = undefined;
+			markParked();
 			setAttemptPhase("parked");
 			finish();
 			terminate();
@@ -739,6 +788,11 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				return;
 			}
 			setAttemptPhase("interrupting");
+			if (!initialPromptResolved) {
+				const stopped = new Error(reason);
+				resolveInitialPrompt(false, stopped);
+				rejectPending(stopped);
+			}
 			let timer: ReturnType<typeof setTimeout> | undefined;
 			const timeout = new Promise<boolean>((resolve) => {
 				timer = setTimeout(() => resolve(false), RPC_ABORT_SETTLE_TIMEOUT_MS);
@@ -813,12 +867,11 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			result.rpcActivity = true;
 		}
 
-		// The child provider adapter disables request-level retries. Cancel Pi's
-		// separate outer turn retry the instant it is scheduled, before another
-		// same-model provider call can begin.
-		if (event.type === "auto_retry_start") {
-			void send({ type: "abort_retry" }).catch(() => undefined);
-		}
+		// Let Pi's outer turn retry run. Grok/xAI long streams commonly drop with
+		// a retryable `terminated` mid-turn; aborting that retry was misread as
+		// "model unavailable" and handed a still-working model back to the parent.
+		// After retries exhaust, dispatch still classifies a settled model-level
+		// failure and hands off.
 
 		// Child RPC mode exposes extension dialogs. Sub-agents are non-interactive:
 		// cancel blocking dialogs so an unrelated child extension cannot deadlock.
@@ -827,11 +880,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			typeof event.id === "string" &&
 			["select", "confirm", "input", "editor"].includes(event.method)
 		) {
-			try {
-				writeLine({ type: "extension_ui_response", id: event.id, cancelled: true });
-			} catch {
-				/* process failure is handled by close/error */
-			}
+			void writeLine({ type: "extension_ui_response", id: event.id, cancelled: true }).catch(() => undefined);
 			return;
 		}
 
@@ -1020,20 +1069,36 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			resolveInitialPrompt(false, new Error("Run was stopped before its initial prompt."));
 			await attemptControl.stop();
 		} else {
-			void send({ type: "prompt", message: asPlainTextRpcPrompt(options.prompt) }).then(
-				() => resolveInitialPrompt(true),
-				(error) => {
-					const promptError = error instanceof Error ? error : new Error(String(error));
-					resolveInitialPrompt(false, promptError);
-					if (finished) return;
-					result.exitCode = 1;
-					result.stopReason = "error";
-					result.errorMessage = promptError.message;
-					result.rpcPromptRejected = true;
-					finish();
-					terminate();
-				},
-			);
+			const failBeforePrompt = (error: Error, startup: boolean): void => {
+				resolveInitialPrompt(false, error);
+				if (finished) return;
+				result.exitCode = 1;
+				result.stopReason = "error";
+				result.errorMessage = error.message;
+				if (startup) result.rpcStartupFailed = true;
+				else result.rpcPromptRejected = true;
+				finish();
+				terminate();
+			};
+			try {
+				await send({ type: "get_state" }, readyTimeoutMs);
+			} catch (error) {
+				const handshakeError = error instanceof Error ? error : new Error(String(error));
+				if (!control?.isParkRequested() && !control?.isStopRequested()) {
+					failBeforePrompt(handshakeError, true);
+				} else {
+					resolveInitialPrompt(false, handshakeError);
+				}
+			}
+			if (!finished && !initialPromptResolved && !control?.isParkRequested() && !control?.isStopRequested()) {
+				void send({ type: "prompt", message: asPlainTextRpcPrompt(options.prompt) }).then(
+					() => resolveInitialPrompt(true),
+					(error) => {
+						const promptError = error instanceof Error ? error : new Error(String(error));
+						failBeforePrompt(promptError, isRpcCommandTimeoutError(promptError.message));
+					},
+				);
+			}
 		}
 		await outcome.promise;
 		terminate();

package/src/spawn.ts

@@ -22,6 +22,7 @@ import {
 	emptyUsage,
 	extractToolErrorText,
 	getPiInvocation,
+	isRpcCommandTimeoutError,
 	RpcRunControl,
 	runRpcAgentAttempt,
 	sessionExists,
@@ -37,6 +38,7 @@ export {
 	DEPTH_ENV_VAR,
 	extractToolErrorText,
 	getPiInvocation,
+	isRpcCommandTimeoutError,
 	RpcRunControl,
 	sessionExists,
 	SUBAGENT_KILL_GRACE_MS,
@@ -201,6 +203,8 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 	if (!isFailedResult(result)) return false;
 	if (result.stopReason === "aborted") return false;
 	if (result.dispatchFailed) return false;
+	if (result.rpcStartupFailed) return false;
+	if (isRpcCommandTimeoutError(result.errorMessage)) return false;
 	if (result.integrationStatus === "retained") return false;
 	if (result.errorMessage?.includes("idle timeout")) return true;
 	if (result.rpcPromptRejected) return true;
@@ -217,6 +221,9 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 	}
 
 	if ((result.failedTools?.length ?? 0) > 0) return false;
+	// No accepted prompt, no activity, and no assistant turn means the provider
+	// was never reached. Stderr or an exit error here is a startup/transport miss.
+	if (!result.rpcPromptAccepted && !result.rpcActivity) return false;
 	return Boolean(
 		result.rpcPromptAccepted ||
 		result.rpcActivity ||
@@ -235,6 +242,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 	if (result.messages.length > 0) return false;
 	const usage = result.usage;
 	if (usage.turns || usage.input || usage.output || usage.cacheRead || usage.cacheWrite || usage.cost) return false;
+	if (result.rpcStartupFailed) return true;
 	if (durationMs > MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS) return false;
 	if (result.stderr.trim().length > 0) return false;
 	if (result.errorMessage && result.errorMessage.trim().length > 0) return false;
@@ -242,7 +250,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 }
 
 export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child exited before any model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child never accepted its initial RPC prompt or produced any model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
 }
 
 export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
@@ -326,6 +334,8 @@ export interface RunSingleOptions {
 	env?: NodeJS.ProcessEnv;
 	/** Stable logical-generation controller shared across retry attempts. */
 	control?: RpcRunControl;
+	rpcReadyTimeoutMs?: number;
+	rpcCommandTimeoutMs?: number;
 }
 
 function controlledDisposition(options: RunSingleOptions, base?: SingleResult): SingleResult | undefined {
@@ -391,6 +401,8 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		onLive: options.onLive,
 		env: options.env,
 		control,
+		rpcReadyTimeoutMs: options.rpcReadyTimeoutMs,
+		rpcCommandTimeoutMs: options.rpcCommandTimeoutMs,
 	});
 	result.task = control?.getObjective() ?? result.task;
 	return result;