@henryqw/pi-subagent 2.11.7 → 3.0.1

package/CONTEXT.md

@@ -17,7 +17,7 @@ Provide validated user Roles, shared task-model Pi launch policy, generic manage
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Default timeouts: 10-minute soft deadline; active model/tool execution or activity within the last minute grants one 5-minute grace period before a hard stop. Every value is configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`softMinutes`, `graceMinutes`, `activeWindowSeconds`).
+- One Delegated Task creates one ephemeral child process and no saved session. Timeout behavior: `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). Configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`idleMinutes`, `maxMinutes`; defaults 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
 - Ambient child extensions and Skills stay disabled; Role explicitly selects extension sources and named Skills. Pi loads Skills supplied by those extension packages or their resource discovery. Omitted Role tools use Pi's effective `defaultTools`; an explicit list sets base tools while loaded extension tools activate automatically.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.

package/README.md

@@ -2,6 +2,11 @@
 
 Delegate one bounded task to one isolated Pi process, or reuse validated Role launch and managed Herdr hosting for durable workers. Main chooses Role and may override shared task-model effort per call.
 
+## Why
+
+- **Created for**: Delegating bounded tasks to isolated child Pi processes while Main retains integration decisions.
+- **Advantage**: Validated Roles, capped concurrency, timeouts, and managed Herdr hosting make delegation predictable.
+
 ## Install
 
 ```bash
@@ -27,9 +32,9 @@ An explicit `model` (`provider/modelId`) overrides `modelClass` and resolves aga
 
 `modelClass` is `fast`, `balanced`, `frontier`, or `fav`. Omitted class uses the shared `pi-subagent/delegateTask` assignment, which defaults to `balanced`. Primary route is resolved against current scoped text models; fallback is tried only before launch. If no route is usable, delegation rejects with `Run /task-models`. A started child is never retried.
 
-Main splits broad work into independent bounded tasks and keeps integration and cross-cutting decisions. Each `task` states its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation. Each call uses the least capable `modelClass` that can reliably complete its task. Independent sibling calls can run concurrently; concurrent edit tasks must own non-overlapping files. Up to five active ephemeral `delegate_task` subagents run per Main; excess calls wait FIFO. Configure the cap with `"maxSubagents"` (positive integer) in `~/.pi/agent/config/pi-subagent/pi-subagent.json`, or override per session with the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable. Child timeouts are configurable with a `"timeout"` object: `{ "softMinutes": 20, "graceMinutes": 10, "activeWindowSeconds": 90 }` (all keys optional; defaults 10/5/60). Invalid config values fall back to the default with a warning; an invalid environment variable fails fast. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
+Main splits broad work into independent bounded tasks and keeps integration and cross-cutting decisions. Each `task` states its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation. Each call uses the least capable `modelClass` that can reliably complete its task. Independent sibling calls can run concurrently; concurrent edit tasks must own non-overlapping files. Up to five active ephemeral `delegate_task` subagents run per Main; excess calls wait FIFO. Configure the cap with `"maxSubagents"` (positive integer) in `~/.pi/agent/config/pi-subagent/pi-subagent.json`, or override per session with the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable. Child timeouts are configurable with a `"timeout"` object: `{ "idleMinutes": 10, "maxMinutes": 30 }` (all keys optional; defaults 10/30; the effective maximum must exceed the idle timeout). Invalid config values fall back to the default with a warning; an invalid environment variable fails fast. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
 
-Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and Skills are off. Role/caller extensions load; those packages' tools and Skills auto-load, plus any extra `skills` names. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. An inactive child times out after 10 minutes; current model/tool execution or activity in the last minute grants one 5-minute grace period, then the child stops. Streaming output is capped at 50 KiB. Unused JSON event types are discarded before payload buffering; consumed or unclassifiable events above 1 MiB fail delegation.
+Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and Skills are off. Role/caller extensions load; those packages' tools and Skills auto-load, plus any extra `skills` names. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. Child timeout behavior uses `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)`: recognized Pi events renew; raw bytes do not; max always terminates. Streaming output is capped at 50 KiB. Unused JSON event types are discarded before payload buffering; consumed or unclassifiable events above 1 MiB fail delegation.
 
 TUI shows one row per Subagent with role, route, task, tokens, and elapsed time. Terminal rows drop after one second.
 

package/extensions/config.ts

@@ -3,12 +3,10 @@ import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export interface SubagentTimeoutConfig {
-	/** Soft deadline in minutes; the child is asked to stop after this. */
-	softMinutes?: number;
-	/** Extra minutes past the soft deadline before a stuck child is killed. */
-	graceMinutes?: number;
-	/** Activity window in seconds that qualifies an active child for grace. */
-	activeWindowSeconds?: number;
+	/** Minutes a child may stay idle before it is asked to stop. */
+	idleMinutes?: number;
+	/** Hard cap in minutes before a child is killed regardless of activity. */
+	maxMinutes?: number;
 }
 
 export interface SubagentConfig {
@@ -28,14 +26,10 @@ const positive = (value: unknown): value is number =>
 // Node clamps setTimeout delays above 2^31 - 1 ms to 1 ms, which would kill
 // every child immediately instead of applying the configured deadline.
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
-// Defaults for fields the user left unset, used when bounding the combined
-// soft + grace hard-deadline delay.
-const DEFAULT_SOFT_MINUTES = 10;
-const DEFAULT_GRACE_MINUTES = 5;
-const TIMEOUT_FIELDS: Array<[keyof SubagentTimeoutConfig, number, string]> = [
-	["softMinutes", 60_000, "minutes"],
-	["graceMinutes", 60_000, "minutes"],
-	["activeWindowSeconds", 1_000, "seconds"],
+export const DEFAULT_TIMEOUT_CONFIG = { idleMinutes: 10, maxMinutes: 30 } as const;
+const TIMEOUT_FIELDS: Array<[keyof SubagentTimeoutConfig, string]> = [
+	["idleMinutes", "minutes"],
+	["maxMinutes", "minutes"],
 ];
 
 /**
@@ -94,15 +88,15 @@ export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConf
 		} else {
 			const timeoutRecord = record.timeout as Record<string, unknown>;
 			const timeout: SubagentTimeoutConfig = {};
-			for (const [key, unitMs, unit] of TIMEOUT_FIELDS) {
+			for (const [key, unit] of TIMEOUT_FIELDS) {
 				const value = timeoutRecord[key];
 				if (value === undefined) continue;
 				if (!positive(value)) {
 					problems.push(`timeout.${key} must be a positive number of ${unit}, got ${JSON.stringify(value)}`);
-				} else if (value * unitMs > MAX_TIMER_DELAY_MS) {
+				} else if (value * 60_000 > MAX_TIMER_DELAY_MS) {
 					problems.push(`timeout.${key} exceeds the maximum supported delay of ${MAX_TIMER_DELAY_MS} ms, got ${JSON.stringify(value)} ${unit}`);
 				} else {
-					(timeout as Record<string, number>)[key] = value;
+					timeout[key] = value;
 				}
 			}
 			for (const key of Object.keys(timeoutRecord)) {
@@ -114,15 +108,14 @@ export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConf
 		}
 	}
 
-	// The hard deadline schedules softMs + graceMs in one timer; the combination
-	// must stay inside Node's limit even when each field fits alone. Falling back
-	// to defaults drops the whole timeout object, matching other invalid values.
+	// The hard cap must exceed the idle deadline or every idle kill is
+	// unreachable. Falling back to defaults drops the whole timeout object,
+	// matching other invalid values.
 	if (config.timeout) {
-		const hardDeadlineMinutes =
-			(config.timeout.softMinutes ?? DEFAULT_SOFT_MINUTES) +
-			(config.timeout.graceMinutes ?? DEFAULT_GRACE_MINUTES);
-		if (hardDeadlineMinutes * 60_000 > MAX_TIMER_DELAY_MS) {
-			problems.push(`timeout softMinutes + graceMinutes must stay within ${MAX_TIMER_DELAY_MS} ms combined, got ${hardDeadlineMinutes} minutes`);
+		const idleMinutes = config.timeout.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes;
+		const maxMinutes = config.timeout.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes;
+		if (maxMinutes <= idleMinutes) {
+			problems.push(`timeout.maxMinutes (${maxMinutes}) must be greater than timeout.idleMinutes (${idleMinutes})`);
 			delete config.timeout;
 		}
 	}

package/extensions/subagent.ts

@@ -3,9 +3,9 @@ import { existsSync } from "node:fs";
 import { basename } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import { type AgentSessionEvent, type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth, type TUI, visibleWidth } from "@earendil-works/pi-tui";
-import { readSubagentConfig, type SubagentTimeoutConfig } from "./config.ts";
+import { DEFAULT_TIMEOUT_CONFIG, readSubagentConfig, type SubagentTimeoutConfig } from "./config.ts";
 import {
 	availableTaskModels,
 	THINKING_LEVELS,
@@ -23,6 +23,31 @@ import { createChildWorktree, createRoleLaunch, finalizeChildWorktree, isProfile
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
+const PI_JSON_EVENTS = {
+	agent_start: true,
+	agent_end: true,
+	agent_settled: true,
+	turn_start: true,
+	turn_end: true,
+	message_start: true,
+	message_update: true,
+	message_end: true,
+	tool_execution_start: true,
+	tool_execution_update: true,
+	tool_execution_end: true,
+	queue_update: true,
+	compaction_start: true,
+	compaction_end: true,
+	entry_appended: true,
+	session_info_changed: true,
+	thinking_level_changed: true,
+	auto_retry_start: true,
+	auto_retry_end: true,
+	summarization_retry_scheduled: true,
+	summarization_retry_attempt_start: true,
+	summarization_retry_finished: true,
+	bash_execution_update: true,
+} satisfies Record<AgentSessionEvent["type"], true>;
 const CONSUMED_JSON_EVENTS = new Set(["message_start", "message_update", "message_end"]);
 const JSON_EVENT_TYPE = /^\s*\{\s*"type"\s*:\s*"([^"\\]+)"/;
 const WIDGET_KEY = "subagent-status";
@@ -30,9 +55,8 @@ const WIDGET_INTERVAL_MS = 80;
 const TERMINAL_DISPLAY_MS = 1_000;
 const MAX_WIDGET_ROWS = 8;
 const DEFAULT_TIMEOUT_POLICY = {
-	softMs: 10 * 60_000,
-	graceMs: 5 * 60_000,
-	activeWindowMs: 60_000,
+	idleMs: DEFAULT_TIMEOUT_CONFIG.idleMinutes * 60_000,
+	maxMs: DEFAULT_TIMEOUT_CONFIG.maxMinutes * 60_000,
 };
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -40,12 +64,10 @@ type TimeoutPolicy = typeof DEFAULT_TIMEOUT_POLICY;
 
 /** Merge validated config-file timeout fields over defaults; absent keys keep defaults. */
 export function resolveTimeoutPolicy(partial: SubagentTimeoutConfig | undefined): TimeoutPolicy {
-	const policy: TimeoutPolicy = { ...DEFAULT_TIMEOUT_POLICY };
-	if (!partial) return policy;
-	if (partial.softMinutes !== undefined) policy.softMs = partial.softMinutes * 60_000;
-	if (partial.graceMinutes !== undefined) policy.graceMs = partial.graceMinutes * 60_000;
-	if (partial.activeWindowSeconds !== undefined) policy.activeWindowMs = partial.activeWindowSeconds * 1_000;
-	return policy;
+	return {
+		idleMs: partial?.idleMinutes === undefined ? DEFAULT_TIMEOUT_POLICY.idleMs : partial.idleMinutes * 60_000,
+		maxMs: partial?.maxMinutes === undefined ? DEFAULT_TIMEOUT_POLICY.maxMs : partial.maxMinutes * 60_000,
+	};
 }
 class SubagentTimeoutError extends Error {}
 type ChildResult = {
@@ -251,21 +273,38 @@ async function runPi(
 		let spawnError: Error | undefined;
 		let protocolError: Error | undefined;
 		let aborted = false;
+		const startedAt = Date.now();
+		const maxDeadline = startedAt + timeoutPolicy.maxMs;
+		let lastEventAt = startedAt;
+		let deadline = Math.min(startedAt + timeoutPolicy.idleMs, maxDeadline);
 		let timedOutAfterMs: number | undefined;
-		let graceGranted = false;
-		let lastActivityAt = Date.now();
-		let modelActive = false;
-		let activeTools = 0;
+		let timeoutReason: "idle" | "maximum" | undefined;
+		let childExited = false;
 		let completedTokens = 0;
 		let currentTokens = 0;
-		let softDeadlineTimer: ReturnType<typeof setTimeout> | undefined;
-		let hardDeadlineTimer: ReturnType<typeof setTimeout> | undefined;
+		let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
 		let killTimer: ReturnType<typeof setTimeout> | undefined;
 
-		const observeEvent = (type: string) => {
-			lastActivityAt = Date.now();
-			if (type === "tool_execution_start") activeTools++;
-			else if (type === "tool_execution_end") activeTools = Math.max(0, activeTools - 1);
+		const scheduleDeadline = () => {
+			if (deadlineTimer) clearTimeout(deadlineTimer);
+			deadline = Math.min(lastEventAt + timeoutPolicy.idleMs, maxDeadline);
+			const scheduledDeadline = deadline;
+			deadlineTimer = setTimeout(
+				() => timeout(scheduledDeadline - startedAt, scheduledDeadline === maxDeadline ? "maximum" : "idle"),
+				Math.max(0, scheduledDeadline - Date.now()),
+			);
+			deadlineTimer.unref();
+		};
+
+		const observeEvent = () => {
+			if (aborted || timedOutAfterMs !== undefined || childExited) return;
+			const now = Date.now();
+			if (now >= deadline) {
+				timeout(deadline - startedAt, deadline === maxDeadline ? "maximum" : "idle");
+				return;
+			}
+			lastEventAt = now;
+			scheduleDeadline();
 		};
 
 		const processLine = (line: string) => {
@@ -278,16 +317,15 @@ async function runPi(
 			}
 			if (!event || typeof event !== "object" || Array.isArray(event)) return;
 			const record = event as Record<string, unknown>;
+			if (typeof record.type !== "string" || !Object.hasOwn(PI_JSON_EVENTS, record.type)) return;
+			observeEvent();
 			if (record.type === "message_start") {
-				if (record.message && typeof record.message === "object" && !Array.isArray(record.message)
-					&& (record.message as Record<string, unknown>).role === "assistant") modelActive = true;
 				partial.prefix = "";
 				partial.totalBytes = 0;
 				hasPartialText = false;
 				return;
 			}
 			if (record.type === "message_update") {
-				modelActive = true;
 				const tokens = usageTokens(record.usage);
 				if (tokens !== undefined) {
 					currentTokens = tokens;
@@ -316,7 +354,6 @@ async function runPi(
 			if (record.message && typeof record.message === "object" && !Array.isArray(record.message)) {
 				const message = record.message as Record<string, unknown>;
 				if (message.role === "assistant") {
-					modelActive = false;
 					completedTokens += usageTokens(message.usage) ?? currentTokens;
 					currentTokens = 0;
 					onTokens?.(completedTokens);
@@ -348,7 +385,6 @@ async function runPi(
 
 		child.stdout.on("data", (data: string) => {
 			if (protocolError) return;
-			lastActivityAt = Date.now();
 			let offset = 0;
 			while (offset < data.length) {
 				const newline = data.indexOf("\n", offset);
@@ -357,23 +393,19 @@ async function runPi(
 				if (!ignoreLine) {
 					linePrefix += part.slice(0, Math.max(0, 256 - linePrefix.length));
 					const eventType = JSON_EVENT_TYPE.exec(linePrefix)?.[1];
-					if (eventType && !lineEventType) {
-						lineEventType = eventType;
-						observeEvent(eventType);
-					}
-					if (eventType && !CONSUMED_JSON_EVENTS.has(eventType)) {
-						ignoreLine = true;
-						lineParts = [];
-						lineBytes = 0;
-					} else {
-						lineBytes += Buffer.byteLength(part, "utf8");
-						if (lineBytes > MAX_JSON_EVENT_BYTES) {
+					if (eventType && !lineEventType) lineEventType = eventType;
+					lineBytes += Buffer.byteLength(part, "utf8");
+					if (lineBytes > MAX_JSON_EVENT_BYTES) {
+						if (lineEventType && !CONSUMED_JSON_EVENTS.has(lineEventType)) {
+							ignoreLine = true;
+							lineParts = [];
+							lineBytes = 0;
+						} else {
 							protocolError = new Error(`Subagent JSON event exceeds ${MAX_JSON_EVENT_BYTES} bytes.`);
 							void killTree(true);
 							return;
 						}
-						if (part) lineParts.push(part);
-					}
+					} else if (part) lineParts.push(part);
 				}
 				if (newline === -1) return;
 				if (!ignoreLine) processLine(lineParts.join(""));
@@ -386,52 +418,65 @@ async function runPi(
 			}
 		});
 		child.stderr.on("data", (data: string) => {
-			lastActivityAt = Date.now();
 			appendBounded(stderr, data);
 		});
 		child.on("error", (error) => { spawnError = error; });
 
-		const stop = () => {
+		const stop = (force = false) => {
+			if (force) {
+				void killTree(true);
+				return;
+			}
 			void killTree(false);
-			killTimer = setTimeout(() => void killTree(true), 5_000);
+			killTimer = setTimeout(
+				() => void killTree(true),
+				Math.min(5_000, Math.max(0, maxDeadline - Date.now())),
+			);
 			killTimer.unref();
 		};
 		const abort = () => {
-			if (timedOutAfterMs !== undefined) return;
+			if (timedOutAfterMs !== undefined || childExited) return;
 			aborted = true;
 			stop();
 		};
-		const timeout = (afterMs: number) => {
-			if (aborted || timedOutAfterMs !== undefined) return;
+		function timeout(afterMs: number, reason: "idle" | "maximum") {
+			if (timedOutAfterMs !== undefined || childExited) return;
+			if (reason === "maximum") {
+				if (!aborted) {
+					timedOutAfterMs = afterMs;
+					timeoutReason = reason;
+				}
+				stop(true);
+				return;
+			}
+			if (aborted) return;
 			timedOutAfterMs = afterMs;
+			timeoutReason = reason;
 			stop();
-		};
-		softDeadlineTimer = setTimeout(() => {
-			const active = modelActive || activeTools > 0 || Date.now() - lastActivityAt <= timeoutPolicy.activeWindowMs;
-			if (active && timeoutPolicy.graceMs > 0) graceGranted = true;
-			else timeout(timeoutPolicy.softMs);
-		}, timeoutPolicy.softMs);
-		softDeadlineTimer.unref();
-		hardDeadlineTimer = setTimeout(
-			() => timeout(timeoutPolicy.softMs + timeoutPolicy.graceMs),
-			timeoutPolicy.softMs + timeoutPolicy.graceMs,
-		);
-		hardDeadlineTimer.unref();
+		}
+		scheduleDeadline();
 		signal?.addEventListener("abort", abort, { once: true });
 		if (signal?.aborted) abort();
 
+		// `close` waits for stdio EOF, which descendants can hold after Pi exits.
+		// Kill the process group at Pi's exit boundary so `close` can settle.
+		child.once("exit", () => {
+			childExited = true;
+			if (deadlineTimer) clearTimeout(deadlineTimer);
+			signal?.removeEventListener("abort", abort);
+			void killTree(true);
+		});
 		child.on("close", async (code) => {
 			if (!protocolError && lineBytes) processLine(lineParts.join(""));
-			// Pi may exit while redirected background commands remain in its process
-			// group. Stop every descendant before callers inspect or prune its cwd.
 			await killTree(true);
-			if (softDeadlineTimer) clearTimeout(softDeadlineTimer);
-			if (hardDeadlineTimer) clearTimeout(hardDeadlineTimer);
+			if (deadlineTimer) clearTimeout(deadlineTimer);
 			if (killTimer) clearTimeout(killTimer);
 			signal?.removeEventListener("abort", abort);
 			if (aborted) reject(new Error("Subagent was aborted."));
 			else if (timedOutAfterMs !== undefined) reject(new SubagentTimeoutError(
-				`Subagent timed out after ${formatElapsed(0, timedOutAfterMs)}${graceGranted ? ` despite active status at the ${formatElapsed(0, timeoutPolicy.softMs)} soft deadline` : " without active status at the soft deadline"}.`,
+				timeoutReason === "maximum"
+					? `Subagent reached its maximum runtime after ${formatElapsed(0, timedOutAfterMs)}.`
+					: `Subagent timed out after ${formatElapsed(0, timeoutPolicy.idleMs)} without a recognized Pi event.`,
 			));
 			else if (protocolError) reject(protocolError);
 			else if (spawnError) reject(spawnError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "2.11.7",
+  "version": "3.0.1",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",