pi-subagents 0.11.1 → 0.11.3

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [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
+- `--no-skills` was missing from the async runner (`subagent-runner.ts`). PR #41 added skill scoping to the sync path but the async runner spawns pi through its own code path, so background subagents with explicit skills still got the full `<available_skills>` catalog injected.
+- `defaultSessionDir` and `sessionDir` with `~` paths (e.g. `"~/.pi/agent/sessions/subagent/"`) were not expanded — `path.resolve("~/...")` treats `~` as a literal directory name. Added tilde expansion matching the existing pattern in `skills.ts`.
+- Multiple subagent calls within a session would collide when `defaultSessionDir` was configured, since it wasn't appending a unique `runId`. Both `defaultSessionDir` and parent-session-derived paths now get `runId` appended.
+
+### Removed
+- Removed exported `resolveSessionRoot()` function and `SessionRootInput` interface. These were introduced by PR #46 but never called in production — the inline resolution logic diverged (always-on sessions, `runId` appended) making the function's contract misleading. Associated tests and dead code from PR #47 scaffolding also removed from `path-handling.test.ts`.
+
 ## [0.11.1] - 2026-03-08
 
 ### Changed

package/README.md

@@ -538,7 +538,7 @@ Notes:
 | `artifacts` | boolean | true | Write debug artifacts |
 | `includeProgress` | boolean | false | Include full progress in result |
 | `share` | boolean | false | Upload session to GitHub Gist (see [Session Sharing](#session-sharing)) |
-| `sessionDir` | string | temp | Directory to store session logs |
+| `sessionDir` | string | - | Override session log directory (takes precedence over `defaultSessionDir` and parent-session-derived path) |
 
 **ChainItem** can be either a sequential step or a parallel step:
 
@@ -604,11 +604,31 @@ Templates support three variables:
 
 This aggregated output becomes `{previous}` for the next step.
 
-## Chain Directory
+## Extension Configuration
+
+`pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`.
+
+### `defaultSessionDir`
 
+`defaultSessionDir` sets the fallback directory used for session logs. Eg:
+
+```json
+{
+  "defaultSessionDir": "~/.pi/agent/sessions/subagent/"
+}
+```
+
+Session root resolution follows this precedence:
+1. `params.sessionDir` from the `subagent` tool call
+2. `config.defaultSessionDir`
+3. Derived from parent session (stored alongside parent session file)
+
+Sessions are always enabled — every subagent run gets a session directory for tracking.
+
+## Chain Directory
 Each chain run creates `<tmpdir>/pi-chain-runs/{runId}/` containing:
 - `context.md` - Scout/context-builder output
-- `plan.md` - Planner output  
+- `plan.md` - Planner output
 - `progress.md` - Worker/reviewer shared progress
 - `parallel-{stepIndex}/` - Subdirectories for parallel step outputs
   - `0-{agent}/output.md` - First parallel task output
@@ -629,7 +649,7 @@ Files per task:
 
 ## Session Logs
 
-Session files (JSONL) are stored under a per-run session dir (temp by default). The session file path is shown in output. Set `sessionDir` to keep session logs outside `<tmpdir>`.
+Session files (JSONL) are stored under a per-run session directory. Directory selection follows the same precedence as session root resolution: explicit `sessionDir` > `config.defaultSessionDir` > parent-session-derived path. The session file path is shown in output.
 
 ## Session Sharing
 

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,48 +55,10 @@ 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);
@@ -119,26 +69,20 @@ export async function runSync(
 		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,
@@ -180,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) => {
@@ -372,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 };
+}