@narumitw/pi-subagents 0.27.0 → 0.30.1

package/README.md

@@ -178,6 +178,10 @@ Run multiple agents in parallel with a shared thinking level and one per-task ov
 }
 ```
 
+Omit `aggregator` entirely when parallel worker outputs should return directly. Do not send `null`,
+empty strings, or an empty object for an unused optional field; for compatibility, an aggregator with
+an empty or whitespace-only `agent` or `task` is treated as absent.
+
 Run parallel workers, then aggregate their results:
 
 ```json
@@ -339,6 +343,9 @@ Existing `subagent` requests remain unchanged:
 | Parallel | Input order, with at most four active children. | Collects all task results; partial worker failure is reported in summaries but does not discard successful results. |
 | Parallel + aggregator | Source input order, then aggregator. | The aggregator runs with both successful outputs and failure descriptions; aggregator failure marks the tool result as an error. |
 
+An aggregator whose `agent` or `task` is empty or whitespace-only is treated as absent, so successful
+parallel outputs remain available instead of being replaced by a malformed fan-in failure.
+
 Timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms. Blocking thinking precedence remains: task/step/aggregator → call → agent setting → child default. Stateful spawn thinking precedence is: `subagent_spawn.thinkingLevel` → agent setting → transport fallback. Project-agent resolution and confirmation behavior is unchanged.
 
 ## 🤖 Built-in agents
@@ -491,7 +498,8 @@ Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-su
 ```txt
 extensions/pi-subagents/
 ├── src/
-│   ├── subagents.ts              # Pi entrypoint and blocking tool schema
+│   ├── index.ts                  # Pi package entrypoint
+│   ├── subagents.ts              # Extension registration and blocking tool schema
 │   ├── stateful.ts               # Detached lifecycle registration and dispatch
 │   ├── stateful-tool-params.ts   # Consolidated action schemas and validation
 │   └── *.ts                      # Package-local discovery, execution, rendering, and config modules
@@ -501,12 +509,12 @@ extensions/pi-subagents/
 └── package.json
 ```
 
-Only `subagents.ts` is a Pi entrypoint; the other source modules are internal. The package exposes its Pi extension through `package.json`:
+`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal. The package exposes its Pi extension through `package.json`:
 
 ```json
 {
   "pi": {
-    "extensions": ["./src/subagents.ts"]
+    "extensions": ["./src/index.ts"]
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.27.0",
+	"version": "0.30.1",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",
@@ -20,7 +20,7 @@
 	],
 	"pi": {
 		"extensions": [
-			"./src/subagents.ts"
+			"./src/index.ts"
 		]
 	},
 	"scripts": {

package/src/execution.ts

@@ -1,13 +1,13 @@
 import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
-	discoverAgents,
 	type AgentConfig,
 	type AgentScope,
+	discoverAgents,
 	type SubagentThinkingLevel,
 } from "./agents.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
-import type { SubagentParams } from "./params.js";
+import { hasUsableAggregator, type SubagentParams } from "./params.js";
 import {
 	buildFanInContext,
 	formatResultFailure,
@@ -107,6 +107,7 @@ export async function executeSubagent(
 ): Promise<AgentToolResult<SubagentDetails> & { isError?: boolean }> {
 			assertSubagentDepthAllowed();
 			const agentScope: AgentScope = params.agentScope ?? "user";
+			const aggregator = hasUsableAggregator(params.aggregator) ? params.aggregator : undefined;
 			const config = readSubagentSettings();
 			const discovery = discoverAgents(ctx.cwd, agentScope, config);
 			const agents = discovery.agents;
@@ -134,7 +135,7 @@ export async function executeSubagent(
 					aggregator,
 				});
 
-			if (modeCount !== 1 || (params.aggregator && !hasTasks)) {
+			if (modeCount !== 1 || (aggregator && !hasTasks)) {
 				const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
 				const reason =
 					modeCount !== 1
@@ -155,7 +156,7 @@ export async function executeSubagent(
 				const requestedAgentNames = new Set<string>();
 				if (params.chain) for (const step of params.chain) requestedAgentNames.add(step.agent);
 				if (params.tasks) for (const t of params.tasks) requestedAgentNames.add(t.agent);
-				if (params.aggregator) requestedAgentNames.add(params.aggregator.agent);
+				if (aggregator) requestedAgentNames.add(aggregator.agent);
 				if (params.agent) requestedAgentNames.add(params.agent);
 
 				const projectAgentsRequested = Array.from(requestedAgentNames)
@@ -286,7 +287,6 @@ export async function executeSubagent(
 					const emitParallelUpdate = () => {
 						status.update(parallelStatus(doneCount, allResults.length, runningCount));
 						if (onUpdate) {
-							const aggregator = params.aggregator;
 							const pendingAggregator: SingleResult | undefined =
 								aggregator && !signal?.aborted && doneCount === allResults.length
 									? {
@@ -368,8 +368,7 @@ export async function executeSubagent(
 					});
 
 					let aggregatorResult: SingleResult | undefined;
-					if (params.aggregator && !signal?.aborted) {
-						const aggregator = params.aggregator;
+					if (aggregator && !signal?.aborted) {
 						status.update(fanInStatus(aggregator.agent));
 						const fanInContext = buildFanInContext(results);
 						const aggregatorTask = truncateUtf8(

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./subagents.js";

package/src/params.ts

@@ -29,13 +29,19 @@ const ChainItem = Type.Object({
 	thinkingLevel: Type.Optional(ThinkingLevelSchema),
 });
 
-const AggregatorItem = Type.Object({
-	agent: Type.String({ description: "Name of the fan-in agent to invoke after parallel tasks complete" }),
-	task: Type.String({ description: "Fan-in task. Use {previous} to include all parallel outputs." }),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the aggregator process" })),
-	timeoutMs: Type.Optional(TimeoutMs),
-	thinkingLevel: Type.Optional(ThinkingLevelSchema),
-});
+const AggregatorItem = Type.Object(
+	{
+		agent: Type.String({ description: "Name of the fan-in agent to invoke after parallel tasks complete" }),
+		task: Type.String({ description: "Fan-in task. Use {previous} to include all parallel outputs." }),
+		cwd: Type.Optional(Type.String({ description: "Working directory for the aggregator process" })),
+		timeoutMs: Type.Optional(TimeoutMs),
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	},
+	{
+		description:
+			"Optional fan-in step for parallel mode. Omit this key entirely when no aggregation is needed; empty or whitespace-only agent/task values are treated as absent.",
+	},
+);
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	description:
@@ -59,3 +65,16 @@ export const SubagentParams = Type.Object({
 });
 
 export type SubagentParams = Static<typeof SubagentParams>;
+
+export function hasUsableAggregator(
+	aggregator: unknown,
+): aggregator is { agent: string; task: string } {
+	if (!aggregator || typeof aggregator !== "object") return false;
+	const candidate = aggregator as { agent?: unknown; task?: unknown };
+	return (
+		typeof candidate.agent === "string" &&
+		candidate.agent.trim().length > 0 &&
+		typeof candidate.task === "string" &&
+		candidate.task.trim().length > 0
+	);
+}

package/src/render.ts

@@ -9,7 +9,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { AgentScope, SubagentThinkingLevel } from "./agents.js";
-import type { SubagentParams } from "./params.js";
+import { hasUsableAggregator, type SubagentParams } from "./params.js";
 import {
 	getResultFinalOutput,
 	isResultError,
@@ -19,6 +19,15 @@ import {
 
 const COLLAPSED_ITEM_COUNT = 10;
 
+function previewTask(task: unknown, maxLength = 40): string {
+	if (typeof task !== "string" || task.length === 0) return "...";
+	return task.length > maxLength ? `${task.slice(0, maxLength)}...` : task;
+}
+
+function previewAgent(agent: unknown): string {
+	return typeof agent === "string" && agent.length > 0 ? agent : "...";
+}
+
 export function formatTokens(count: number): string {
 	if (count < 1000) return count.toString();
 	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
@@ -180,16 +189,16 @@ export function renderSubagentCall(args: SubagentParams, theme: Theme) {
 			theme.fg("accent", `chain (${args.chain.length} steps)`) +
 			theme.fg("muted", ` [${scope}]`);
 		for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
-			const step = args.chain[i];
+			const step = args.chain[i] as { agent?: unknown; task?: unknown } | undefined;
 			// Clean up {previous} placeholder for display
-			const cleanTask = step.task.replace(/\{previous\}/g, "").trim();
-			const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask;
+			const cleanTask =
+				typeof step?.task === "string" ? step.task.replace(/\{previous\}/g, "").trim() : undefined;
 			text +=
 				"\n  " +
 				theme.fg("muted", `${i + 1}.`) +
 				" " +
-				theme.fg("accent", step.agent) +
-				theme.fg("dim", ` ${preview}`);
+				theme.fg("accent", previewAgent(step?.agent)) +
+				theme.fg("dim", ` ${previewTask(cleanTask)}`);
 		}
 		if (args.chain.length > 3)
 			text += `\n  ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`;
@@ -200,30 +209,23 @@ export function renderSubagentCall(args: SubagentParams, theme: Theme) {
 			theme.fg("toolTitle", theme.bold("subagent ")) +
 			theme.fg("accent", `parallel (${args.tasks.length} tasks)`) +
 			theme.fg("muted", ` [${scope}]`);
-		for (const t of args.tasks.slice(0, 3)) {
-			const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task;
-			text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", ` ${preview}`)}`;
+		for (const task of args.tasks.slice(0, 3)) {
+			const item = task as { agent?: unknown; task?: unknown } | undefined;
+			text += `\n  ${theme.fg("accent", previewAgent(item?.agent))}${theme.fg("dim", ` ${previewTask(item?.task)}`)}`;
 		}
 		if (args.tasks.length > 3)
 			text += `\n  ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`;
-		if (args.aggregator) {
-			const preview =
-				args.aggregator.task.length > 40
-					? `${args.aggregator.task.slice(0, 40)}...`
-					: args.aggregator.task;
-			text += `\n  ${theme.fg("muted", "fan-in → ")}${theme.fg("accent", args.aggregator.agent)}${theme.fg(
+		if (hasUsableAggregator(args.aggregator)) {
+			const aggregator = args.aggregator;
+			text += `\n  ${theme.fg("muted", "fan-in → ")}${theme.fg("accent", previewAgent(aggregator.agent))}${theme.fg(
 				"dim",
-				` ${preview}`,
+				` ${previewTask(aggregator.task)}`,
 			)}`;
 		}
 		return new Text(text, 0, 0);
 	}
-	const agentName = args.agent || "...";
-	const preview = args.task
-		? args.task.length > 60
-			? `${args.task.slice(0, 60)}...`
-			: args.task
-		: "...";
+	const agentName = previewAgent(args.agent);
+	const preview = previewTask(args.task, 60);
 	let text =
 		theme.fg("toolTitle", theme.bold("subagent ")) +
 		theme.fg("accent", agentName) +

package/src/subagents.ts

@@ -41,6 +41,7 @@ export default function (pi: ExtensionAPI) {
 			"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
 			"Use a blocking subagent single, parallel, chain, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
 			"If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the hard max 8, and avoid write-heavy implementation touching the same files or shared state.",
+			"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
 			'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
 			"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
 		],