oira666_pi-subagent 0.3.10 → 0.3.12

package/README.md

@@ -130,7 +130,7 @@ The Markdown body becomes the agent's system prompt (appended to Pi's default, n
 
 ## Delegation Guards
 
-Depth and cycle guards prevent runaway recursive delegation. Layer availability is evaluated for the child being launched: depth 1 is the first layer, and `PI_SUBAGENT_MAX_DEPTH` is the last layer. The bundled `team-lead` agent sets `last-layer: disabled` so it cannot consume the final delegation layer.
+Depth and cycle guards prevent runaway recursive delegation. Layer availability is evaluated for the child being launched: depth 1 is the first layer, and `PI_SUBAGENT_MAX_DEPTH` is the last layer. The bundled `team-lead` agent sets `last-layer: disabled` so it cannot consume the final delegation layer. Cycle checks are applied per task: in a mixed parallel call, cyclic tasks fail while legal siblings still run.
 
 | Config                         | Default | Description                                      |
 | ------------------------------ | ------- | ------------------------------------------------ |
@@ -160,6 +160,12 @@ cancellation, the runner terminates the child process tree and bounds cleanup;
 even if a wedged OS process never reports `close`, the tool returns an error
 result so every waiting parent can settle.
 
+RPC completion is based on Pi's `agent_settled` event—not `agent_end`.
+`agent_end` is only a low-level run boundary and may be followed by Pi's normal
+provider retry, overflow compaction, or queued continuation. Rejected prompt
+commands, signal exits, and processes that exit before `agent_settled` are
+reported immediately as failures.
+
 | Env Var | Default | Description |
 | --- | --- | --- |
 | `PI_SUBAGENT_STARTUP_TIMEOUT` | `120000` | Milliseconds allowed to reach the first model turn; `0` disables |
@@ -169,7 +175,10 @@ result so every waiting parent can settle.
 ## Timestamps & Status Footer
 
 Subagent tool calls and live activity lines render a dim `hh:mm:ss` timestamp
-(call start, per-subagent run start, and each live log entry).
+(call start, per-subagent run start, and each live log entry). The collapsed tool
+row keeps the normal compact progress text. Press `Ctrl+O` to expand it into the
+subagent tree immediately; every running node shows its latest six activity
+lines (thinking, tool starts/completions, and completed turns).
 
 In the interactive TUI the extension publishes the combined `total` usage line
 (parent + all subagents, recursively) via Pi's normal `ctx.ui.setStatus()`
@@ -190,6 +199,7 @@ The same detection also runs after navigating the session tree in the TUI (Esc n
 - TUI mode asks: **Resume subagents?**
 - Non-UI modes (`pi -p`, JSON/RPC) resume automatically.
 - Already-finished subagents are reused as completed; unfinished ones continue from their own saved sessions.
+- Durable child refs retain final output, own usage, model, and tool counts, so completed siblings survive a JSON/session restart without becoming `(no output)` or losing accounting.
 - Nested subagents use the same mechanism recursively.
 - Provider fallback goes through the selected model's effective Pi provider, so custom providers, custom APIs, auth-derived endpoints, headers, and provider-scoped environment are preserved.
 - Pending resume state and delayed callbacks are discarded on `/resume`, `/new`, `/fork`, and `/reload`, preventing stale work from an old runtime from leaking into the replacement session.
@@ -220,6 +230,7 @@ Naming is deliberately unambiguous: `agent` (in `subagents`) selects an agent
 subagent *instance* by its unique name.
 
 - All resumes in one call run **in parallel**.
+- The preferred shape is `{"resumes":[...]}`. For compatibility, the common single-item shorthand `{"subagent":"name","task":"..."}` is normalized automatically before validation.
 - Names are unique within one delegation tree (everything spawned from one
   top-level session) and are persisted in a registry file under the subagent
   session root, so they survive restarts: you can resume a subagent in a later
@@ -336,7 +347,7 @@ interface SingleResult {
   agent: string;                        // agent name
   agentSource: "user" | "project" | "builtin" | "unknown";
   task: string;                         // task string passed to this agent
-  exitCode: number;                     // 0 = success, >0 = error, -1 = still running
+  exitCode: number;                     // 0 = process success, >0 = error, -1 = still running
   messages: Message[];                  // full conversation history of the subagent
   stderr: string;
   usage: UsageStats;                    // this agent's OWN token usage only

package/index.ts

@@ -76,6 +76,8 @@ import {
   getNestedSubagentResults,
   isResultError,
   isSubagentDetails,
+  prepareResumeArguments,
+  subagentDetailsHaveErrors,
   isSubagentToolName,
   RESUME_SUBAGENTS_TOOL_NAME,
   SUBAGENT_TOOL_NAME,
@@ -442,7 +444,14 @@ function liveDetailsSignature(details: SubagentDetails): string {
 function collectLiveUsageSummary(details: SubagentDetails): SubagentUsageSummary {
   const summary = emptyUsageSummary();
   for (const result of details.results) {
+    if (result.subtreeUsageSummary) {
+      addUsageSummary(summary, result.subtreeUsageSummary);
+      continue;
+    }
     addUsageSummary(summary, usageSummaryFromUsage(result.usage));
+    if (result.priorDescendantUsageSummary) {
+      addUsageSummary(summary, result.priorDescendantUsageSummary);
+    }
 
     const completedNested = getNestedSubagentResults(result.messages ?? []);
     const completedNestedIds = new Set<string>();
@@ -519,15 +528,6 @@ function collectCombinedUsageStatusLine(
   return formatCombinedUsageStatusLine(parentUsage, subagents.subagentCount);
 }
 
-function getCycleViolations(
-  requestedNames: Set<string>,
-  ancestorAgentStack: string[],
-): string[] {
-  if (requestedNames.size === 0 || ancestorAgentStack.length === 0) return [];
-  const stackSet = new Set(ancestorAgentStack);
-  return Array.from(requestedNames).filter((name) => stackSet.has(name));
-}
-
 /** Get project-local agents referenced by the current request. */
 function getRequestedProjectAgents(
   agents: AgentConfig[],
@@ -983,6 +983,8 @@ export default function (pi: ExtensionAPI) {
   const activeSubagents = new Map<number, { agent: string; task: string; taskIndex: number; handle: RunningSubagentHandle; name?: string }>();
   /** Names with a resume in flight in this process (same-process race guard). */
   const activeResumeNames = new Set<string>();
+  /** Tool calls whose execute result requested an actual Pi error result. */
+  const forcedErrorToolCallIds = new Set<string>();
   const activeSubagentUsageSummaries = new Map<string, SubagentUsageSummary>();
   const latestBroadcastTargets = {
     all: [] as BroadcastTarget[],
@@ -1515,6 +1517,7 @@ export default function (pi: ExtensionAPI) {
     latestSessionCtx = undefined;
     resumeModelRegistry = undefined;
     activeSubagentUsageSummaries.clear();
+    forcedErrorToolCallIds.clear();
     activeSubagents.clear();
   });
 
@@ -1655,6 +1658,16 @@ export default function (pi: ExtensionAPI) {
     scheduleSessionTask(() => updateCombinedUsageStatus(ctx), 0);
   });
 
+  // A custom tool must throw to make Pi set isError, but throwing would discard
+  // the durable subagent details needed for crash-resume. Convert our internal
+  // outcome marker through Pi's supported tool_result middleware instead.
+  pi.on("tool_result", (event: any) => {
+    if (!isSubagentToolName(event?.toolName)) return;
+    const detailsFailed = subagentDetailsHaveErrors(event.details);
+    const forced = forcedErrorToolCallIds.delete(event.toolCallId);
+    if (forced || detailsFailed) return { isError: true };
+  });
+
   pi.on("tool_execution_end", (event, ctx) => {
     latestSessionCtx = ctx;
     if (isSubagentToolName(event.toolName)) {
@@ -1776,6 +1789,7 @@ ${agentList}\n\n${subagentsGuidance}${resumeGuidance ? `\n\n${resumeGuidance}` :
       parameters: SubagentParams,
 
       async execute(toolCallId, params, signal, onUpdate, ctx) {
+        const toolResult = await (async () => {
         try {
           recordToolCallStart(toolCallId);
           updateLatestBroadcastTargets(undefined);
@@ -1797,6 +1811,7 @@ ${agentList}\n\n${subagentsGuidance}${resumeGuidance ? `\n\n${resumeGuidance}` :
                 },
               ],
               details: makeDetails("single")([]),
+              isError: true,
             };
           }
 
@@ -1813,35 +1828,20 @@ ${agentList}\n\n${subagentsGuidance}${resumeGuidance ? `\n\n${resumeGuidance}` :
             onUpdate?.(partial);
           };
 
-          // Security: guard project-local agents before running
-          const requested = new Set<string>();
-          for (const t of tasks) requested.add(t.agent);
-
+          // Apply whole-call security preflight only to tasks that can actually
+          // run. Cyclic tasks become aligned structured failures in the runner;
+          // they must not block legal siblings or consume durable names.
+          const cyclicTaskIndexes = new Set<number>();
           if (preventCycles) {
-            const cycleViolations = getCycleViolations(
-              requested,
-              ancestorAgentStack,
-            );
-            if (cycleViolations.length > 0) {
-              const stackText =
-                ancestorAgentStack.length > 0
-                  ? ancestorAgentStack.join(" -> ")
-                  : "(root)";
-              return {
-                content: [
-                  {
-                    type: "text",
-                    text: `Blocked: delegation cycle detected. Requested agent(s) already in the delegation stack: ${cycleViolations.join(", ")}.
-Current stack: ${stackText}
-
-This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A).`,
-                  },
-                ],
-                details: makeDetails(executionMode)([]),
-                isError: true,
-              };
-            }
+            const stack = new Set(ancestorAgentStack);
+            tasks.forEach((task, index) => {
+              if (stack.has(task.agent)) cyclicTaskIndexes.add(index);
+            });
           }
+          const requested = new Set<string>();
+          tasks.forEach((task, index) => {
+            if (!cyclicTaskIndexes.has(index)) requested.add(task.agent);
+          });
 
           const requestedProjectAgents = getRequestedProjectAgents(
             agents,
@@ -1907,7 +1907,7 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
           if (currentNamesFile) {
             const pendingAllocation = tasks
               .map((task, index) => ({ task, index }))
-              .filter(({ index }) => !names[index]);
+              .filter(({ index }) => !cyclicTaskIndexes.has(index) && !names[index]);
             if (pendingAllocation.length > 0) {
               try {
                 const allocated = await allocateSubagentNames(
@@ -1980,7 +1980,9 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
             isError: true,
           };
         }
-
+        })();
+        if ((toolResult as any)?.isError === true) forcedErrorToolCallIds.add(toolCallId);
+        return toolResult;
       },
 
       renderCall: (args, theme, context) => renderCall(args, theme, context),
@@ -2003,8 +2005,10 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
         'Example: { resumes: [{ subagent: "code-writer-01", task: "Also update the tests." }] }',
       ].join("\n"),
       parameters: ResumeSubagentsParams,
+      prepareArguments: prepareResumeArguments,
 
       async execute(toolCallId, params, signal, onUpdate, ctx) {
+        const toolResult = await (async () => {
         const markedNames: string[] = [];
         try {
           recordToolCallStart(toolCallId);
@@ -2192,6 +2196,9 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
             }
           }
         }
+        })();
+        if ((toolResult as any)?.isError === true) forcedErrorToolCallIds.add(toolCallId);
+        return toolResult;
       },
 
       renderCall: (args, theme, context) => renderResumeCall(args, theme, context),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-subagent",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
   "type": "module",
   "main": "index.ts",

package/render.ts

@@ -7,12 +7,19 @@
  */
 
 import { Container, Spacer, Text } from "@mariozechner/pi-tui";
-import type { SubagentDetails } from "./types.js";
+import {
+	MAX_LIVE_LOG_ENTRIES,
+	isResultError,
+	isSubagentDetails,
+	type SingleResult,
+	type SubagentDetails,
+} from "./types.js";
 import {
 	type ThemeFg,
 	buildTopLevelNodes,
 	countNodes,
 	formatClockTime,
+	formatLiveLogEntry,
 	hasNestedChildren,
 	renderTreeLines,
 	setBroadcastNumberingActive,
@@ -122,37 +129,119 @@ export function renderResumeCall(
 // renderResult — shown after the tool completes / streams updates
 // ---------------------------------------------------------------------------
 
+function getResultText(
+	result: { content?: Array<{ type: string; text?: string }> },
+): string {
+	const first = Array.isArray(result.content) ? result.content[0] : undefined;
+	return first?.type === "text" && typeof first.text === "string" && first.text
+		? first.text
+		: "(no output)";
+}
+
+function compactText(text: string, maxLength = 240): string {
+	const firstLine = text.replace(/\r\n?/g, "\n").split("\n").find((line) => line.trim()) ?? "(no output)";
+	return truncate(firstLine, maxLength);
+}
+
+function isRenderableResult(value: unknown): value is SingleResult {
+	return value !== null &&
+		typeof value === "object" &&
+		!Array.isArray(value) &&
+		typeof (value as Partial<SingleResult>).agent === "string" &&
+		typeof (value as Partial<SingleResult>).exitCode === "number";
+}
+
+function getCollapsedResultText(details: SubagentDetails, fallbackText: string): string {
+	const results = details.results.filter(isRenderableResult);
+	if (results.length === 0) return compactText(fallbackText);
+
+	const running = results.filter((item) => item.exitCode === -1).length;
+	const finished = results.length - running;
+	const succeeded = results.filter((item) => item.exitCode === 0 && !isResultError(item)).length;
+	const failed = finished - succeeded;
+
+	if (details.mode === "parallel") {
+		return running > 0
+			? `Parallel: ${finished}/${results.length} done, ${running} running...`
+			: `Parallel: ${succeeded}/${results.length} succeeded${failed > 0 ? `, ${failed} failed` : ""}`;
+	}
+
+	const item = results[0];
+	if (item.exitCode === -1) return `Agent ${item.agent}: running...`;
+	if (isResultError(item)) {
+		const reason = [item.errorMessage, item.stderr, item.stopReason]
+			.find((value): value is string => typeof value === "string" && value.length > 0);
+		return `Agent ${item.agent}: failed${reason ? ` — ${compactText(reason, 180)}` : ""}`;
+	}
+	return `Agent ${item.agent}: completed`;
+}
+
 export function renderResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: unknown },
-	_expanded: boolean,
+	expanded: boolean,
 	theme: { fg: ThemeFg; bold: (s: string) => string },
 ): Container | Text {
-	const details = result.details as SubagentDetails | undefined;
-	if (!details || details.results.length === 0) {
-		const first = result.content[0];
-		return new Text(first?.type === "text" && first.text ? first.text : "(no output)", 0, 0);
+	const fallbackText = getResultText(result);
+
+	// Keep the normal row compact. Ctrl+O switches to the live tree below.
+	if (!expanded) {
+		const text = isSubagentDetails(result.details)
+			? getCollapsedResultText(result.details, fallbackText)
+			: compactText(fallbackText);
+		return new Text(text, 0, 0);
 	}
 
-	const nodes = buildTopLevelNodes(details);
-	const counts = countNodes(nodes);
-	const showOutputPreview = !hasNestedChildren(nodes);
-	const icon = counts.running > 0
-		? theme.fg("warning", "⏳")
-		: counts.error > 0
-			? theme.fg("error", "❌")
-			: theme.fg("success", "✅");
+	if (!isSubagentDetails(result.details) || result.details.results.length === 0) {
+		return new Text(fallbackText, 0, 0);
+	}
+	const details: SubagentDetails = result.details;
 
-	const container = new Container();
-	container.addChild(
-		new Text(
-			`${icon} ${theme.fg("toolTitle", theme.bold("subagent tree "))}${theme.fg("dim", topLevelSummary(details, counts))}`,
-			0,
-			0,
-		),
-	);
+	try {
+		const nodes = buildTopLevelNodes(details);
+		const counts = countNodes(nodes);
+		const showOutputPreview = !hasNestedChildren(nodes);
+		const icon = counts.running > 0
+			? theme.fg("warning", "⏳")
+			: counts.error > 0
+				? theme.fg("error", "❌")
+				: theme.fg("success", "✅");
 
-	container.addChild(new Spacer(1));
-	container.addChild(new Text(renderTreeLines(nodes, theme, showOutputPreview).join("\n"), 0, 0));
+		const container = new Container();
+		container.addChild(
+			new Text(
+				`${icon} ${theme.fg("toolTitle", theme.bold("subagent tree "))}${theme.fg("dim", topLevelSummary(details, counts))}`,
+				0,
+				0,
+			),
+		);
 
-	return container;
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(renderTreeLines(nodes, theme, showOutputPreview).join("\n"), 0, 0));
+		return container;
+	} catch {
+		// Pi falls back to raw result.content when a custom renderer throws, which
+		// made Ctrl+O appear broken until the offending rolling log entry expired.
+		// Keep an expanded tree visible even for malformed third-party/RPC data.
+		const lines: string[] = [];
+		for (const item of details.results) {
+			const agent = typeof item?.agent === "string" ? item.agent : "unknown agent";
+			const icon = item?.exitCode === -1
+				? theme.fg("warning", "⏳")
+				: item?.exitCode === 0
+					? theme.fg("success", "✅")
+					: theme.fg("error", "❌");
+			lines.push(`${icon} ${theme.fg("accent", agent)}`);
+			const liveLog = Array.isArray(item?.liveLog)
+				? item.liveLog.slice(-MAX_LIVE_LOG_ENTRIES)
+				: [];
+			for (const entry of liveLog) {
+				lines.push(`  ${formatLiveLogEntry(entry, theme)}`);
+			}
+		}
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("subagent tree"))}\n${lines.join("\n") || fallbackText}`,
+			0,
+			0,
+		);
+	}
 }