@narumitw/pi-subagents 0.13.1 → 0.14.1

package/src/subagents.ts

@@ -18,6 +18,7 @@ import { SubagentParams } from "./params.js";
 import { executeSubagent } from "./execution.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
 import type { SubagentDetails } from "./runner.js";
+import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
 	pi.registerTool<typeof SubagentParams, SubagentDetails>({
@@ -34,8 +35,12 @@ export default function (pi: ExtensionAPI) {
 			"Decide whether to spawn 0, 1, or multiple subagents for independent research, review, verification, or multi-step work in isolated Pi processes.",
 		promptGuidelines: [
 			"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
-			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, or tasks requiring frequent user back-and-forth.",
-			"Use one subagent for isolated research, broad command output, planning, or independent review/verification that benefits from a separate context.",
+			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work needed for the main agent's next action.",
+			"A single blocking subagent call should be used only when independent context, high-volume output isolation, or an external review is worth waiting for; otherwise do the task in the main agent.",
+			"For one-shot parallel work, use a single subagent call with tasks instead of repeated subagent_spawn calls, even when the user explicitly requests multiple agents.",
+			"When subagent_spawn is available, use it only when detached delegation has a concrete parallel, isolation, or specialization benefit; otherwise keep the work in the main agent.",
+			"After detached spawn, continue useful non-overlapping work when available, or call subagent_wait when coordination is the only useful next action; do not yield permanently while delegated work remains unresolved.",
+			"Consume detached completion messages and synthesize their results before finishing; interrupt or close agents that are no longer needed.",
 			"Use subagent parallel mode with 2-4 parallel read-only subagents when work has broad independent branches; prefer scout or reviewer for fan-out and add an aggregator when synthesis helps.",
 			"Use more than 4 subagent tasks only when clearly justified by distinct independent branches, and stay within the existing hard max 8 parallel tasks.",
 			"Do not use subagent parallel mode for write-heavy implementation touching the same files or shared state; serialize those changes in the main agent or one worker.",
@@ -57,8 +62,13 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.on("tool_result", (event) => {
+		if (event.toolName !== "subagent") return;
+		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError) return { isError: true };
+	});
 
 	registerSubagentConfigCommand(pi);
+	registerStatefulSubagents(pi);
 }
 export { formatTokens, formatUsageStats } from "./render.js";
 export { buildPiArgs } from "./runner.js";

package/src/subprocess-transport.ts

@@ -0,0 +1,50 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { discoverAgents } from "./agents.js";
+import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
+import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
+import {
+	buildStatefulTurnPrompt,
+	resolveStatefulTurnTimeout,
+} from "./stateful-prompt.js";
+import type { SubagentTransport } from "./transport.js";
+
+export class SubprocessTransport implements SubagentTransport {
+	readonly kind = "subprocess" as const;
+
+	constructor(private readonly ctx: ExtensionContext) {}
+
+	async runTurn(record: ManagedAgent, task: string, signal: AbortSignal): Promise<TurnOutcome> {
+		const settings = readSubagentSettings();
+		const discovery = discoverAgents(record.cwd, record.agentScope ?? "user", settings);
+		const agent = discovery.agents.find((candidate) => candidate.name === record.agent);
+		const boundedTask = buildStatefulTurnPrompt(record, task);
+		const makeDetails = (results: SubagentDetails["results"]): SubagentDetails => ({
+			mode: "single",
+			agentScope: record.agentScope ?? "user",
+			projectAgentsDir: discovery.projectAgentsDir,
+			results,
+		});
+		const single = await runSingleAgent(
+			record.cwd,
+			discovery.agents,
+			record.agent,
+			boundedTask.text,
+			undefined,
+			undefined,
+			signal,
+			resolveSubagentThinkingLevel(discovery.agents, record.agent),
+			resolveStatefulTurnTimeout(agent),
+			undefined,
+			makeDetails,
+		);
+		return {
+			output: getResultFinalOutput(single),
+			exitCode: single.exitCode,
+			aborted: single.aborted,
+			truncated: single.truncated || boundedTask.truncated,
+			error: single.errorMessage || single.stderr || undefined,
+			policy: single.policy,
+		};
+	}
+}

package/src/transport.ts

@@ -0,0 +1,30 @@
+import type { ManagedAgent, TurnOutcome } from "./registry.js";
+
+export interface SubagentTransport {
+	readonly kind: "subprocess" | "in-process" | "fake";
+	runTurn(agent: ManagedAgent, task: string, signal: AbortSignal): Promise<TurnOutcome>;
+	release?(agent: ManagedAgent): Promise<void>;
+	shutdown?(): Promise<void>;
+}
+
+export type AgentTurnRunner = (
+	agent: ManagedAgent,
+	task: string,
+	signal: AbortSignal,
+) => Promise<TurnOutcome>;
+
+export class FunctionTransport implements SubagentTransport {
+	readonly kind = "fake" as const;
+
+	constructor(private readonly runner: AgentTurnRunner) {}
+
+	runTurn(agent: ManagedAgent, task: string, signal: AbortSignal): Promise<TurnOutcome> {
+		return this.runner(agent, task, signal);
+	}
+}
+
+export function normalizeTransport(
+	transport: SubagentTransport | AgentTurnRunner,
+): SubagentTransport {
+	return typeof transport === "function" ? new FunctionTransport(transport) : transport;
+}

package/src/workspace.ts

@@ -0,0 +1,116 @@
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const WORKTREE_PREFIX = "pi-subagent-worktree-";
+
+export interface IsolatedWorkspace {
+	mode: "worktree";
+	path: string;
+	rootPath: string;
+	repositoryRoot: string;
+}
+
+export class WorkspaceManager {
+	private readonly owned = new Map<string, IsolatedWorkspace>();
+
+	async create(ownerId: string, cwd: string): Promise<IsolatedWorkspace> {
+		if (this.owned.has(ownerId)) throw new Error(`Workspace owner already exists: ${ownerId}`);
+		const resolvedCwd = path.resolve(cwd);
+		const repositoryRoot = (
+			await execFileAsync("git", ["-C", resolvedCwd, "rev-parse", "--show-toplevel"])
+		).stdout.trim();
+		const relativeCwd = path.relative(repositoryRoot, resolvedCwd);
+		if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
+			throw new Error("Subagent cwd is outside the Git repository");
+		}
+		const status = (
+			await execFileAsync("git", ["-C", repositoryRoot, "status", "--porcelain"])
+		).stdout;
+		if (status.trim()) throw new Error("Isolated subagent workspace requires a clean Git repository");
+		const rootPath = await fs.promises.mkdtemp(path.join(os.tmpdir(), WORKTREE_PREFIX));
+		let registered = false;
+		try {
+			await execFileAsync("git", [
+				"-C",
+				repositoryRoot,
+				"worktree",
+				"add",
+				"--detach",
+				rootPath,
+				"HEAD",
+			]);
+			registered = true;
+			await fs.promises.writeFile(`${rootPath}.owner`, ownerId, { mode: 0o600 });
+			const workspace = {
+				mode: "worktree" as const,
+				path: path.join(rootPath, relativeCwd),
+				rootPath,
+				repositoryRoot,
+			};
+			this.owned.set(ownerId, workspace);
+			return workspace;
+		} catch (error) {
+			if (registered) {
+				await execFileAsync("git", [
+					"-C",
+					repositoryRoot,
+					"worktree",
+					"remove",
+					"--force",
+					rootPath,
+				]).catch(() => undefined);
+			}
+			await fs.promises.rm(rootPath, { recursive: true, force: true });
+			await fs.promises.rm(`${rootPath}.owner`, { force: true });
+			throw error;
+		}
+	}
+
+	async cleanup(ownerId: string): Promise<void> {
+		const workspace = this.owned.get(ownerId);
+		if (!workspace) return;
+		if (!(await this.isOwned(workspace.rootPath, ownerId))) {
+			throw new Error(`Refusing to clean unowned subagent workspace: ${workspace.rootPath}`);
+		}
+		this.owned.delete(ownerId);
+		await execFileAsync("git", [
+			"-C",
+			workspace.repositoryRoot,
+			"worktree",
+			"remove",
+			"--force",
+			workspace.rootPath,
+		]).catch(async () => {
+			await fs.promises.rm(workspace.rootPath, { recursive: true, force: true });
+			await execFileAsync("git", ["-C", workspace.repositoryRoot, "worktree", "prune"])
+				.catch(() => undefined);
+		});
+		await fs.promises.rm(`${workspace.rootPath}.owner`, { force: true });
+	}
+
+	async cleanupAll(): Promise<void> {
+		const results = await Promise.allSettled(
+			[...this.owned.keys()].map((ownerId) => this.cleanup(ownerId)),
+		);
+		const failures = results.filter((result) => result.status === "rejected");
+		if (failures.length > 0) {
+			throw new AggregateError(
+				failures.map((failure) => (failure as PromiseRejectedResult).reason),
+				`Failed to clean ${failures.length} subagent workspace(s)`,
+			);
+		}
+	}
+
+	private async isOwned(rootPath: string, ownerId: string): Promise<boolean> {
+		if (!path.basename(rootPath).startsWith(WORKTREE_PREFIX)) return false;
+		try {
+			return (await fs.promises.readFile(`${rootPath}.owner`, "utf8")) === ownerId;
+		} catch {
+			return false;
+		}
+	}
+}