@henryqw/pi-subagent 2.3.3 → 2.3.5

package/CONTEXT.md

@@ -18,6 +18,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. 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.
+- Up to four active ephemeral `delegate_task` children run per Main; 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.
 - 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,7 @@ 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.
 
-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.
+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 four active ephemeral `delegate_task` children run per Main; excess calls wait FIFO. 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.
 

package/extensions/subagent.ts

@@ -12,6 +12,7 @@ const MODEL_CLASSES = PROFILE_NAMES;
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
+const MAX_ACTIVE_CHILDREN = 4;
 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";
@@ -433,6 +434,35 @@ export default function subagentExtension(
 	timeoutPolicy: TimeoutPolicy = DEFAULT_TIMEOUT_POLICY,
 ): void {
 	const widgetItems = new Map<string, WidgetItem>();
+	let activeChildren = 0;
+	const queuedChildren: Array<() => void> = [];
+	const acquireChildPermit = (signal: AbortSignal | undefined): Promise<void> => {
+		if (signal?.aborted) return Promise.reject(new Error("Subagent was aborted."));
+		if (activeChildren < MAX_ACTIVE_CHILDREN) {
+			activeChildren++;
+			return Promise.resolve();
+		}
+		return new Promise<void>((resolve, reject) => {
+			function abort() {
+				const index = queuedChildren.indexOf(grant);
+				if (index < 0) return;
+				queuedChildren.splice(index, 1);
+				signal?.removeEventListener("abort", abort);
+				reject(new Error("Subagent was aborted."));
+			}
+			const grant = () => {
+				signal?.removeEventListener("abort", abort);
+				resolve();
+			};
+			queuedChildren.push(grant);
+			signal?.addEventListener("abort", abort, { once: true });
+		});
+	};
+	const releaseChildPermit = () => {
+		const grant = queuedChildren.shift();
+		if (grant) grant();
+		else activeChildren--;
+	};
 	let widgetInstalled = false;
 	let widgetTimer: ReturnType<typeof setInterval> | undefined;
 	let spinnerIndex = 0;
@@ -555,9 +585,10 @@ export default function subagentExtension(
 				);
 			}
 
+			const args = ["--mode", "json", "-p", ...launch.args, `Task: ${task}`];
+			await acquireChildPermit(signal);
 			let widgetStatus: Exclude<WidgetStatus, "working"> = "failure";
 			try {
-				const args = ["--mode", "json", "-p", ...launch.args, `Task: ${task}`];
 				startWidgetItem(toolCallId, role.name, launch.model.id, thinkingLevel, task, ctx);
 				const details = { role: role.name, model: modelReferenceValue, thinkingLevel };
 				const result = await runPi(
@@ -578,6 +609,7 @@ export default function subagentExtension(
 				if (signal?.aborted && !(error instanceof SubagentTimeoutError)) widgetStatus = "aborted";
 				throw error;
 			} finally {
+				releaseChildPermit();
 				finishWidgetItem(toolCallId, widgetStatus);
 			}
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -38,7 +38,7 @@
     "@earendil-works/pi-ai": "^0.84.2",
     "@earendil-works/pi-coding-agent": "^0.84.2",
     "@earendil-works/pi-tui": "^0.84.2",
-    "typebox": "^1.3.13"
+    "typebox": "^1.3.15"
   },
   "repository": {
     "type": "git",