pi-subagents 0.11.2 → 0.11.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.11.3] - 2026-03-17
+
+### Changed
+- Decomposed `index.ts` (1,450 → ~350 lines) into focused modules: `subagent-executor.ts`, `async-job-tracker.ts`, `result-watcher.ts`, `slash-commands.ts`. Shared mutable state centralized in `SubagentState` interface. Three identical session handlers collapsed into one.
+- Extracted shared pi CLI arg-builder (`pi-args.ts`) from duplicated logic in `execution.ts` and `subagent-runner.ts`.
+- Consolidated `mapConcurrent` (canonical in `parallel-utils.ts`, re-exported from `utils.ts`), `aggregateParallelOutputs` (canonical in `parallel-utils.ts` with optional header formatter, re-exported from `settings.ts`), and `parseFrontmatter` (extracted to `frontmatter.ts`).
+
 ## [0.11.2] - 2026-03-11
 
 ### Fixed

package/agents.ts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { KNOWN_FIELDS } from "./agent-serializer.js";
 import { parseChain } from "./chain-serializer.js";
 import { mergeAgentsForScope } from "./agent-selection.js";
+import { parseFrontmatter } from "./frontmatter.js";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -58,36 +59,6 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
-function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
-	const frontmatter: Record<string, string> = {};
-	const normalized = content.replace(/\r\n/g, "\n");
-
-	if (!normalized.startsWith("---")) {
-		return { frontmatter, body: normalized };
-	}
-
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) {
-		return { frontmatter, body: normalized };
-	}
-
-	const frontmatterBlock = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
-
-	for (const line of frontmatterBlock.split("\n")) {
-		const match = line.match(/^([\w-]+):\s*(.*)$/);
-		if (match) {
-			let value = match[2].trim();
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
-			frontmatter[match[1]] = value;
-		}
-	}
-
-	return { frontmatter, body };
-}
-
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 

package/async-execution.ts

@@ -10,7 +10,7 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
-import { applyThinkingSuffix } from "./execution.js";
+import { applyThinkingSuffix } from "./pi-args.js";
 import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
 import { isParallelStep, resolveStepBehavior, type ChainStep, type ParallelStep, type SequentialStep, type StepOverrides } from "./settings.js";
 import type { RunnerStep } from "./parallel-utils.js";

package/async-job-tracker.ts

@@ -0,0 +1,123 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import * as path from "node:path";
+import { renderWidget } from "./render.js";
+import {
+	type SubagentState,
+	POLL_INTERVAL_MS,
+} from "./types.js";
+import { readStatus } from "./utils.js";
+
+export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string): {
+	ensurePoller: () => void;
+	handleStarted: (data: unknown) => void;
+	handleComplete: (data: unknown) => void;
+	resetJobs: (ctx?: ExtensionContext) => void;
+} {
+	const ensurePoller = () => {
+		if (state.poller) return;
+		state.poller = setInterval(() => {
+			if (!state.lastUiContext || !state.lastUiContext.hasUI) return;
+			if (state.asyncJobs.size === 0) {
+				renderWidget(state.lastUiContext, []);
+				if (state.poller) {
+					clearInterval(state.poller);
+					state.poller = null;
+				}
+				return;
+			}
+
+			for (const job of state.asyncJobs.values()) {
+				if (job.status === "complete" || job.status === "failed") {
+					continue;
+				}
+				const status = readStatus(job.asyncDir);
+				if (status) {
+					job.status = status.state;
+					job.mode = status.mode;
+					job.currentStep = status.currentStep ?? job.currentStep;
+					job.stepsTotal = status.steps?.length ?? job.stepsTotal;
+					job.startedAt = status.startedAt ?? job.startedAt;
+					job.updatedAt = status.lastUpdate ?? Date.now();
+					if (status.steps?.length) {
+						job.agents = status.steps.map((step) => step.agent);
+					}
+					job.sessionDir = status.sessionDir ?? job.sessionDir;
+					job.outputFile = status.outputFile ?? job.outputFile;
+					job.totalTokens = status.totalTokens ?? job.totalTokens;
+					job.sessionFile = status.sessionFile ?? job.sessionFile;
+				} else {
+					job.status = job.status === "queued" ? "running" : job.status;
+					job.updatedAt = Date.now();
+				}
+			}
+
+			renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
+		}, POLL_INTERVAL_MS);
+		state.poller.unref?.();
+	};
+
+	const handleStarted = (data: unknown) => {
+		const info = data as {
+			id?: string;
+			asyncDir?: string;
+			agent?: string;
+			chain?: string[];
+		};
+		if (!info.id) return;
+		const now = Date.now();
+		const asyncDir = info.asyncDir ?? path.join(asyncDirRoot, info.id);
+		const agents = info.chain && info.chain.length > 0 ? info.chain : info.agent ? [info.agent] : undefined;
+		state.asyncJobs.set(info.id, {
+			asyncId: info.id,
+			asyncDir,
+			status: "queued",
+			mode: info.chain ? "chain" : "single",
+			agents,
+			stepsTotal: agents?.length,
+			startedAt: now,
+			updatedAt: now,
+		});
+		if (state.lastUiContext) {
+			renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
+			ensurePoller();
+		}
+	};
+
+	const handleComplete = (data: unknown) => {
+		const result = data as { id?: string; success?: boolean; asyncDir?: string };
+		const asyncId = result.id;
+		if (!asyncId) return;
+		const job = state.asyncJobs.get(asyncId);
+		if (job) {
+			job.status = result.success ? "complete" : "failed";
+			job.updatedAt = Date.now();
+			if (result.asyncDir) job.asyncDir = result.asyncDir;
+		}
+		if (state.lastUiContext) {
+			renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
+		}
+		const timer = setTimeout(() => {
+			state.cleanupTimers.delete(asyncId);
+			state.asyncJobs.delete(asyncId);
+			if (state.lastUiContext) {
+				renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
+			}
+		}, 10000);
+		state.cleanupTimers.set(asyncId, timer);
+	};
+
+	const resetJobs = (ctx?: ExtensionContext) => {
+		for (const timer of state.cleanupTimers.values()) {
+			clearTimeout(timer);
+		}
+		state.cleanupTimers.clear();
+		state.asyncJobs.clear();
+		state.resultFileCoalescer.clear();
+		if (ctx?.hasUI) {
+			state.lastUiContext = ctx;
+			renderWidget(ctx, []);
+		}
+	};
+
+	return { ensurePoller, handleStarted, handleComplete, resetJobs };
+}

package/chain-serializer.ts

@@ -1,34 +1,5 @@
 import type { ChainConfig, ChainStepConfig } from "./agents.js";
-
-function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
-	const frontmatter: Record<string, string> = {};
-	const normalized = content.replace(/\r\n/g, "\n");
-
-	if (!normalized.startsWith("---")) {
-		return { frontmatter, body: normalized };
-	}
-
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) {
-		return { frontmatter, body: normalized };
-	}
-
-	const frontmatterBlock = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
-
-	for (const line of frontmatterBlock.split("\n")) {
-		const match = line.match(/^([\w-]+):\s*(.*)$/);
-		if (match) {
-			let value = match[2].trim();
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
-			frontmatter[match[1]] = value;
-		}
-	}
-
-	return { frontmatter, body };
-}
+import { parseFrontmatter } from "./frontmatter.js";
 
 function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 	const lines = sectionBody.split("\n");

package/execution.ts

@@ -3,9 +3,6 @@
  */
 
 import { spawn } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 import type { Message } from "@mariozechner/pi-ai";
 import type { AgentConfig } from "./agents.js";
 import {
@@ -24,7 +21,6 @@ import {
 	getSubagentDepthEnv,
 } from "./types.js";
 import {
-	writePrompt,
 	getFinalOutput,
 	findLatestSessionFile,
 	detectSubagentError,
@@ -34,15 +30,7 @@ import {
 import { buildSkillInjection, resolveSkills } from "./skills.js";
 import { getPiSpawnCommand } from "./pi-spawn.js";
 import { createJsonlWriter } from "./jsonl-writer.js";
-
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
-
-export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
-	if (!model || !thinking || thinking === "off") return model;
-	const colonIdx = model.lastIndexOf(":");
-	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) return model;
-	return `${model}:${thinking}`;
-}
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "./pi-args.js";
 
 /**
  * Run a subagent synchronously (blocking until complete)
@@ -67,85 +55,34 @@ export async function runSync(
 		};
 	}
 
-	const args = ["--mode", "json", "-p"];
 	const shareEnabled = options.share === true;
 	const sessionEnabled = Boolean(options.sessionDir) || shareEnabled;
-	if (!sessionEnabled) {
-		args.push("--no-session");
-	}
-	if (options.sessionDir) {
-		try {
-			fs.mkdirSync(options.sessionDir, { recursive: true });
-		} catch {}
-		args.push("--session-dir", options.sessionDir);
-	}
 	const effectiveModel = modelOverride ?? agent.model;
 	const modelArg = applyThinkingSuffix(effectiveModel, agent.thinking);
-	// Use --models (not --model) because pi CLI silently ignores --model
-	// without a companion --provider flag. --models resolves the provider
-	// automatically via resolveModelScope. See: #8
-	if (modelArg) args.push("--models", modelArg);
-	const toolExtensionPaths: string[] = [];
-	if (agent.tools?.length) {
-		const builtinTools: string[] = [];
-		for (const tool of agent.tools) {
-			if (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")) {
-				toolExtensionPaths.push(tool);
-			} else {
-				builtinTools.push(tool);
-			}
-		}
-		if (builtinTools.length > 0) {
-			args.push("--tools", builtinTools.join(","));
-		}
-	}
-	if (agent.extensions !== undefined) {
-		args.push("--no-extensions");
-		for (const extPath of agent.extensions) {
-			args.push("--extension", extPath);
-		}
-	} else {
-		for (const extPath of toolExtensionPaths) {
-			args.push("--extension", extPath);
-		}
-	}
 
 	const skillNames = options.skills ?? agent.skills ?? [];
 	const { resolved: resolvedSkills, missing: missingSkills } = resolveSkills(skillNames, runtimeCwd);
 
-	// When explicit skills are specified (via options or agent config), disable
-	// pi's own skill discovery so the spawned process doesn't inject the full
-	// <available_skills> catalog.  This mirrors how extensions are scoped above.
-	if (skillNames.length > 0) {
-		args.push("--no-skills");
-	}
-
 	let systemPrompt = agent.systemPrompt?.trim() || "";
 	if (resolvedSkills.length > 0) {
 		const skillInjection = buildSkillInjection(resolvedSkills);
 		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${skillInjection}` : skillInjection;
 	}
 
-	let tmpDir: string | null = null;
-	if (systemPrompt) {
-		const tmp = writePrompt(agent.name, systemPrompt);
-		tmpDir = tmp.dir;
-		args.push("--append-system-prompt", tmp.path);
-	}
-
-	// When the task is too long for a CLI argument (Windows ENAMETOOLONG),
-	// write it to a temp file and use pi's @file syntax instead.
-	const TASK_ARG_LIMIT = 8000;
-	if (task.length > TASK_ARG_LIMIT) {
-		if (!tmpDir) {
-			tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
-		}
-		const taskFilePath = path.join(tmpDir, "task.md");
-		fs.writeFileSync(taskFilePath, `Task: ${task}`, { mode: 0o600 });
-		args.push(`@${taskFilePath}`);
-	} else {
-		args.push(`Task: ${task}`);
-	}
+	const { args, env: sharedEnv, tempDir } = buildPiArgs({
+		baseArgs: ["--mode", "json", "-p"],
+		task,
+		sessionEnabled,
+		sessionDir: options.sessionDir,
+		model: effectiveModel,
+		thinking: agent.thinking,
+		tools: agent.tools,
+		extensions: agent.extensions,
+		skills: skillNames,
+		systemPrompt,
+		mcpDirectTools: agent.mcpDirectTools,
+		promptFileStem: agent.name,
+	});
 
 	const result: SingleResult = {
 		agent: agentName,
@@ -187,13 +124,7 @@ export async function runSync(
 		}
 	}
 
-	const spawnEnv = { ...process.env, ...getSubagentDepthEnv() };
-	const mcpDirect = agent.mcpDirectTools;
-	if (mcpDirect?.length) {
-		spawnEnv.MCP_DIRECT_TOOLS = mcpDirect.join(",");
-	} else {
-		spawnEnv.MCP_DIRECT_TOOLS = "__none__";
-	}
+	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv() };
 
 	let closeJsonlWriter: (() => Promise<void>) | undefined;
 	const exitCode = await new Promise<number>((resolve) => {
@@ -379,7 +310,7 @@ export async function runSync(
 		} catch {}
 	}
 
-	if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+	cleanupTempDir(tempDir);
 	result.exitCode = exitCode;
 
 	if (exitCode === 0 && !result.error) {

package/frontmatter.ts

@@ -0,0 +1,29 @@
+export function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+	const frontmatter: Record<string, string> = {};
+	const normalized = content.replace(/\r\n/g, "\n");
+
+	if (!normalized.startsWith("---")) {
+		return { frontmatter, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalized };
+	}
+
+	const frontmatterBlock = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	for (const line of frontmatterBlock.split("\n")) {
+		const match = line.match(/^([\w-]+):\s*(.*)$/);
+		if (match) {
+			let value = match[2].trim();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			frontmatter[match[1]] = value;
+		}
+	}
+
+	return { frontmatter, body };
+}