@henryqw/pi-subagent 2.3.1 → 2.3.3

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.
+- One Delegated Task creates one ephemeral child process and no saved session. Its soft deadline is 10 minutes; active model/tool execution or activity within the last minute grants one 5-minute grace period before a hard stop.
 - 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.
 - Main selects Role and may override Model Class per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.

package/README.md

@@ -25,7 +25,9 @@ pi install npm:@henryqw/pi-subagent
 
 `modelClass` is `fast`, `balanced`, or `frontier`. 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.
 
-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. 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.
+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.
+
+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.
 
 TUI shows one row per Subagent with role, route, task, tokens, and elapsed time. Terminal rows drop after one second.
 

package/extensions/subagent.ts

@@ -18,9 +18,16 @@ const WIDGET_KEY = "subagent-status";
 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,
+};
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
+type TimeoutPolicy = typeof DEFAULT_TIMEOUT_POLICY;
 type ModelClass = ProfileName;
+class SubagentTimeoutError extends Error {}
 type ChildResult = {
 	exitCode: number;
 	output: string;
@@ -192,6 +199,7 @@ async function runPi(
 	signal: AbortSignal | undefined,
 	onUpdate: ((text: string) => void) | undefined,
 	onTokens: ((tokens: number) => void) | undefined,
+	timeoutPolicy: TimeoutPolicy,
 ): Promise<ChildResult> {
 	if (signal?.aborted) throw new Error("Subagent was aborted.");
 	return await new Promise<ChildResult>((resolve, reject) => {
@@ -207,6 +215,7 @@ async function runPi(
 		let lineParts: string[] = [];
 		let lineBytes = 0;
 		let linePrefix = "";
+		let lineEventType: string | undefined;
 		let ignoreLine = false;
 		let output = "";
 		const stderr = { prefix: "", totalBytes: 0 };
@@ -217,10 +226,23 @@ async function runPi(
 		let spawnError: Error | undefined;
 		let protocolError: Error | undefined;
 		let aborted = false;
+		let timedOutAfterMs: number | undefined;
+		let graceGranted = false;
+		let lastActivityAt = Date.now();
+		let modelActive = false;
+		let activeTools = 0;
 		let completedTokens = 0;
 		let currentTokens = 0;
+		let softDeadlineTimer: ReturnType<typeof setTimeout> | undefined;
+		let hardDeadlineTimer: 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 processLine = (line: string) => {
 			if (!line.trim()) return;
 			let event: unknown;
@@ -232,12 +254,15 @@ async function runPi(
 			if (!event || typeof event !== "object" || Array.isArray(event)) return;
 			const record = event as Record<string, unknown>;
 			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;
@@ -266,6 +291,7 @@ 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);
@@ -293,6 +319,7 @@ 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);
@@ -301,6 +328,10 @@ 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 = [];
@@ -320,27 +351,57 @@ async function runPi(
 				lineParts = [];
 				lineBytes = 0;
 				linePrefix = "";
+				lineEventType = undefined;
 				ignoreLine = false;
 				offset = newline + 1;
 			}
 		});
-		child.stderr.on("data", (data: string) => appendBounded(stderr, data));
+		child.stderr.on("data", (data: string) => {
+			lastActivityAt = Date.now();
+			appendBounded(stderr, data);
+		});
 		child.on("error", (error) => { spawnError = error; });
 
-		const abort = () => {
-			aborted = true;
+		const stop = () => {
 			killTree(false);
 			killTimer = setTimeout(() => killTree(true), 5_000);
 			killTimer.unref();
 		};
+		const abort = () => {
+			if (timedOutAfterMs !== undefined) return;
+			aborted = true;
+			stop();
+		};
+		const timeout = (afterMs: number) => {
+			if (aborted || timedOutAfterMs !== undefined) return;
+			timedOutAfterMs = afterMs;
+			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();
 		signal?.addEventListener("abort", abort, { once: true });
+		if (signal?.aborted) abort();
 
 		child.on("close", (code) => {
 			if (!protocolError && lineBytes) processLine(lineParts.join(""));
-			if (aborted) killTree(true);
+			if (aborted || timedOutAfterMs !== undefined) killTree(true);
+			if (softDeadlineTimer) clearTimeout(softDeadlineTimer);
+			if (hardDeadlineTimer) clearTimeout(hardDeadlineTimer);
 			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"}.`,
+			));
 			else if (protocolError) reject(protocolError);
 			else if (spawnError) reject(spawnError);
 			else resolve({ exitCode: code ?? 1, output, stderr: boundedText(stderr), stopReason, errorMessage });
@@ -350,7 +411,9 @@ async function runPi(
 
 const Parameters = Type.Object({
 	role: Type.String({ description: "Configured Subagent role name" }),
-	task: Type.String({ description: "One bounded task with needed context and expected result" }),
+	task: Type.String({
+		description: "Bounded task packet: objective; exact scope and exclusions; relevant context and constraints; expected deliverable; validation. Never the whole parent request.",
+	}),
 	modelClass: Type.Optional(StringEnum(MODEL_CLASSES, {
 		description: "Classify task complexity: fast for narrow lookups or mechanical edits; balanced for normal bounded work; frontier for ambiguous, cross-cutting, or high-risk reasoning. Defaults to the shared pi-subagent/delegateTask assignment.",
 	})),
@@ -365,7 +428,10 @@ const roleSummary = (): string => {
 	}
 };
 
-export default function subagentExtension(pi: ExtensionAPI): void {
+export default function subagentExtension(
+	pi: ExtensionAPI,
+	timeoutPolicy: TimeoutPolicy = DEFAULT_TIMEOUT_POLICY,
+): void {
 	const widgetItems = new Map<string, WidgetItem>();
 	let widgetInstalled = false;
 	let widgetTimer: ReturnType<typeof setInterval> | undefined;
@@ -457,7 +523,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "delegate_task",
 		label: "Subagent",
-		description: `Delegate one bounded task to one isolated Pi Subagent. Roles: ${roleSummary()}. Choose fast for narrow work, balanced for normal work, or frontier for ambiguous and high-risk work; omit modelClass to use shared task-model settings. Request concise conclusions and file/line references; split broad scouting work.`,
+		description: `Delegate one bounded, independently executable task to one isolated Pi Subagent. Roles: ${roleSummary()}. Choose fast for narrow work, balanced for normal work, or frontier for ambiguous and high-risk work; omit modelClass to use shared task-model settings.`,
+		promptSnippet: "Delegate one bounded, independently executable task to an isolated role",
+		promptGuidelines: [
+			"Before calling delegate_task, split broad work into the smallest independent bounded tasks; keep integration and cross-cutting decisions in Main.",
+			"Each delegate_task task must state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; never pass the parent request unchanged.",
+			"For each delegate_task call, choose the least capable modelClass that can reliably complete the task: fast for narrow work, balanced for normal work, and frontier only for ambiguous, cross-cutting, or high-risk work.",
+			"Submit independent delegate_task calls together for parallel execution. Parallel edits must own non-overlapping files; otherwise sequence them. Use the minimum number of Subagents needed.",
+		],
 		parameters: Parameters,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const task = cleanText(params.task, "task", "delegate_task");
@@ -493,6 +566,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					signal,
 					(text) => onUpdate?.({ content: [{ type: "text", text }], details }),
 					(tokens) => updateWidgetTokens(toolCallId, tokens),
+					timeoutPolicy,
 				);
 				const failed = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 				widgetStatus = result.stopReason === "aborted" ? "aborted" : failed ? "failure" : "success";
@@ -501,7 +575,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					: result.output || "(no output)");
 				return { content: [{ type: "text" as const, text }], details, ...(failed ? { isError: true } : {}) };
 			} catch (error) {
-				if (signal?.aborted) widgetStatus = "aborted";
+				if (signal?.aborted && !(error instanceof SubagentTimeoutError)) widgetStatus = "aborted";
 				throw error;
 			} finally {
 				finishWidgetItem(toolCallId, widgetStatus);

package/package.json

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