@narumitw/pi-subagents 0.42.0 → 0.43.1

package/src/stateful-guidance.ts

@@ -0,0 +1,35 @@
+import type { CompletionDelivery } from "./agents.js";
+
+export function createSpawnPromptGuidelines(
+	completionDelivery: CompletionDelivery,
+	blockingEnabled = true,
+): string[] {
+	const deliveryGuidance =
+		completionDelivery === "auto-resume"
+			? blockingEnabled
+				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
+				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result."
+			: blockingEnabled
+				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result."
+				: "With subagent_spawn completion delivery set to next-turn (the default), use subagent_spawn only when the current response does not depend on its result; complete final-answer-dependent work directly because an idle root is not awakened.";
+	const noLocalWorkGuidance =
+		completionDelivery === "auto-resume"
+			? "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response; auto-resume will request a synthesis turn after completion."
+			: "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response only when the current response does not depend on its result; next-turn delivery will not wake an idle root.";
+	return [
+		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly.",
+		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
+		deliveryGuidance,
+		"Use a single subagent_spawn only for a concrete bounded subtask that can run independently and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
+		...(blockingEnabled
+			? [
+					"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
+					"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
+				]
+			: []),
+		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
+		noLocalWorkGuidance,
+		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
+		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_manage action "list" or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
+	];
+}

package/src/stateful-lifecycle.ts

@@ -0,0 +1,31 @@
+import type { AgentRegistry } from "./registry.js";
+import type { WorkspaceManager } from "./workspace.js";
+
+export async function disposeStatefulRuntime(
+	registry: AgentRegistry | undefined,
+	workspaceManager: WorkspaceManager,
+): Promise<unknown[]> {
+	const errors: unknown[] = [];
+	try {
+		await registry?.shutdown();
+	} catch (error) {
+		errors.push(error);
+	}
+	try {
+		await workspaceManager.cleanupAll();
+	} catch (error) {
+		errors.push(error);
+	}
+	return errors;
+}
+
+export function assertCurrentSpawn(
+	signal: AbortSignal | undefined,
+	generation: number,
+	currentGeneration: number,
+): void {
+	if (!signal?.aborted && generation === currentGeneration) return;
+	const error = new Error("Subagent spawn owner was replaced or aborted");
+	error.name = "AbortError";
+	throw error;
+}

package/src/stateful-render.ts

@@ -0,0 +1,249 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+	COLLAPSED_LIST_LIMIT,
+	expansionHint,
+	type RenderStatus,
+	recordList,
+	recordValue,
+	renderFallbackResult,
+	safeBlock,
+	safeLine,
+	statusBadge,
+	stringValue,
+	type ToolRendererContext,
+	textResult,
+	toolHeader,
+} from "./render-common.js";
+
+export type StatefulRenderTool = "spawn" | "send" | "manage" | "mailbox";
+
+export function createStatefulToolRenderer(tool: StatefulRenderTool) {
+	return {
+		renderCall(args: unknown, theme: Theme) {
+			return renderStatefulCall(tool, recordValue(args) ?? {}, theme);
+		},
+		renderResult(
+			result: AgentToolResult<unknown>,
+			options: ToolRenderResultOptions,
+			theme: Theme,
+			context: ToolRendererContext<unknown>,
+		) {
+			return renderStatefulResult(tool, result, options, theme, context);
+		},
+	};
+}
+
+function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unknown>, theme: Theme) {
+	if (tool === "spawn") {
+		const metadata = [
+			`[${safeLine(args.agentScope, "user", 64)}]`,
+			"detached",
+			safeLine(args.workspaceMode, "shared", 64),
+		];
+		if (typeof args.thinkingLevel === "string") metadata.push(`thinking:${args.thinkingLevel}`);
+		return new Text(
+			[
+				toolHeader(theme, "subagent_spawn", args.agent, metadata),
+				`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
+			].join("\n"),
+			0,
+			0,
+		);
+	}
+	if (tool === "send") {
+		return new Text(
+			[
+				toolHeader(theme, "subagent_send", args.agentId, ["follow-up"]),
+				`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
+			].join("\n"),
+			0,
+			0,
+		);
+	}
+	if (tool === "manage") {
+		const metadata: string[] = [];
+		if (typeof args.agentId === "string") metadata.push(`id:${safeLine(args.agentId, "", 256)}`);
+		if (args.subtree === true) metadata.push("subtree");
+		if (args.includeClosed === true) metadata.push("include closed");
+		return new Text(toolHeader(theme, "subagent_manage", args.action, metadata), 0, 0);
+	}
+	const metadata = [`id:${safeLine(args.agentId, "...", 256)}`];
+	if (args.action === "read") {
+		metadata.push(args.acknowledge === false ? "leave unread" : "acknowledge");
+	}
+	const lines = [toolHeader(theme, "subagent_mailbox", args.action, metadata)];
+	if (args.action === "send") {
+		lines.push(`  ${theme.fg("dim", safeLine(args.message, "...", 2 * 1024))}`);
+	}
+	return new Text(lines.join("\n"), 0, 0);
+}
+
+function renderStatefulResult(
+	tool: StatefulRenderTool,
+	result: AgentToolResult<unknown>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	context: ToolRendererContext<unknown>,
+) {
+	const details = recordValue(result.details);
+	const args = recordValue(context.args) ?? {};
+	if (!details) return renderFallbackResult(result, options, theme, context.isError);
+	if (tool === "spawn" || tool === "send") {
+		const agent = recordValue(details.agent);
+		if (!agent) return renderFallbackResult(result, options, theme, context.isError);
+		return new Text(renderAgentResult(agent, result, options.expanded, theme), 0, 0);
+	}
+	if (tool === "manage") {
+		return new Text(renderManageResult(args, details, result, options.expanded, theme), 0, 0);
+	}
+	return new Text(renderMailboxResult(args, details, options.expanded, theme), 0, 0);
+}
+
+function renderAgentResult(
+	agent: Record<string, unknown>,
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const state = safeLine(agent.state, "unknown", 128);
+	const lines = [
+		`${statusBadge(theme, lifecycleStatus(state))} · ${theme.fg("accent", safeLine(agent.id, "agent", 256))} · ${theme.fg("toolOutput", safeLine(agent.agent, "subagent", 256))} · ${theme.fg("muted", state)}`,
+	];
+	const thinking = stringValue(agent.thinkingLevel);
+	const unread = typeof agent.unreadMessages === "number" ? agent.unreadMessages : 0;
+	if (thinking || unread > 0) {
+		lines.push(
+			theme.fg(
+				"dim",
+				[thinking && `thinking:${safeLine(thinking, "", 128)}`, unread > 0 && `unread:${unread}`]
+					.filter(Boolean)
+					.join(" · "),
+			),
+		);
+	}
+	if (expanded) {
+		const task = safeBlock(agent.currentTask, "", 2 * 1024).trim();
+		const error = safeBlock(agent.error, "", 2 * 1024).trim();
+		if (task) lines.push(theme.fg("dim", `task: ${task}`));
+		if (error) lines.push(theme.fg("error", `error: ${error}`));
+		const content = safeBlock(textResult(result), "", 8 * 1024).trim();
+		if (content) lines.push(theme.fg("toolOutput", content));
+	} else lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function renderManageResult(
+	args: Record<string, unknown>,
+	details: Record<string, unknown>,
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const action = safeLine(args.action, "action", 128);
+	const agents = recordList(details.agents);
+	const primary = recordValue(details.agent);
+	if (action === "list") {
+		const lines = [
+			`${statusBadge(theme, "completed")} · list · ${agents.length} agent${agents.length === 1 ? "" : "s"}`,
+		];
+		const selected = expanded ? agents : agents.slice(0, COLLAPSED_LIST_LIMIT);
+		for (const agent of selected) lines.push(formatAgentLine(agent, theme, expanded));
+		if (agents.length === 0) lines.push(theme.fg("muted", "(no retained agents)"));
+		if (agents.length > selected.length)
+			lines.push(theme.fg("muted", `… ${agents.length - selected.length} omitted`));
+		if (!expanded && agents.length > 0) lines.push(expansionHint());
+		return lines.join("\n");
+	}
+
+	const subtree = args.subtree === true;
+	const affected = subtree ? agents.length : agents.length > 0 ? agents.length : primary ? 1 : 0;
+	const status: RenderStatus = action === "interrupt" ? "interrupted" : "closed";
+	const lines = [
+		`${statusBadge(theme, status)} · ${affected} agent${affected === 1 ? "" : "s"}${subtree ? theme.fg("muted", " · subtree") : ""}`,
+	];
+	const selected = agents.length > 0 ? agents : !subtree && primary ? [primary] : [];
+	for (const agent of expanded ? selected : selected.slice(0, COLLAPSED_LIST_LIMIT)) {
+		lines.push(formatAgentLine(agent, theme, expanded));
+	}
+	if (selected.length === 0) {
+		const content = safeBlock(textResult(result), "(no output)", 8 * 1024);
+		lines.push(theme.fg("toolOutput", content));
+	}
+	if (!expanded && selected.length > 0) lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function renderMailboxResult(
+	args: Record<string, unknown>,
+	details: Record<string, unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const action = safeLine(args.action, "action", 64);
+	if (action === "send") {
+		const message = recordValue(details.message);
+		if (!message) return `${statusBadge(theme, "completed")} · Queued message`;
+		const lines = [
+			`${theme.fg("success", "✓")} ${theme.fg("success", "Queued")} · ${theme.fg("accent", safeLine(message.id, "message", 256))} · ${theme.fg("muted", `to ${safeLine(message.recipientId, safeLine(args.agentId), 256)}`)}`,
+		];
+		if (expanded) {
+			lines.push(theme.fg("toolOutput", safeBlock(message.content, "(empty message)", 2 * 1024)));
+		} else lines.push(expansionHint());
+		return lines.join("\n");
+	}
+
+	const messages = recordList(details.messages);
+	const acknowledged = args.acknowledge === false ? "left unread" : "acknowledged";
+	const lines = [
+		`${statusBadge(theme, "completed")} · ${messages.length} message${messages.length === 1 ? "" : "s"} · ${acknowledged}`,
+	];
+	const selected = expanded ? messages : messages.slice(0, COLLAPSED_LIST_LIMIT);
+	for (const message of selected) {
+		const content = expanded
+			? safeBlock(message.content, "(empty message)", 2 * 1024)
+			: safeLine(message.content, "(empty message)", 512);
+		lines.push(
+			`${theme.fg("muted", "• ")}${theme.fg("accent", safeLine(message.id, "message", 256))} ${theme.fg("muted", `from ${safeLine(message.senderId, "unknown", 256)}: `)}${theme.fg("toolOutput", content)}`,
+		);
+	}
+	if (messages.length === 0) lines.push(theme.fg("muted", "(no unread messages)"));
+	if (messages.length > selected.length)
+		lines.push(theme.fg("muted", `… ${messages.length - selected.length} omitted`));
+	if (!expanded && messages.length > 0) lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function formatAgentLine(agent: Record<string, unknown>, theme: Theme, expanded: boolean): string {
+	const unread = typeof agent.unreadMessages === "number" ? agent.unreadMessages : 0;
+	const lines = [
+		`${theme.fg("muted", "• ")}${theme.fg("accent", safeLine(agent.id, "agent", 256))} ${theme.fg("toolOutput", safeLine(agent.agent, "subagent", 256))} ${theme.fg("muted", safeLine(agent.state, "unknown", 128))}${unread > 0 ? theme.fg("warning", ` · unread:${unread}`) : ""}`,
+	];
+	if (expanded) {
+		const task = safeBlock(agent.currentTask, "", 2 * 1024).trim();
+		const error = safeBlock(agent.error, "", 2 * 1024).trim();
+		if (task) lines.push(`  ${theme.fg("dim", `task: ${task}`)}`);
+		if (error) lines.push(`  ${theme.fg("error", `error: ${error}`)}`);
+	}
+	return lines.join("\n");
+}
+
+function lifecycleStatus(state: string): RenderStatus {
+	switch (state) {
+		case "starting":
+			return "starting";
+		case "running":
+			return "running";
+		case "idle":
+			return "idle";
+		case "failed":
+			return "failed";
+		case "interrupted":
+			return "interrupted";
+		case "closed":
+			return "closed";
+		default:
+			return "completed";
+	}
+}

package/src/stateful-safety.ts

@@ -0,0 +1,91 @@
+import { realpathSync } from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentScope, discoverAgents, type SubagentSettings } from "./agents.js";
+import type { AgentRegistry, ManagedAgent } from "./registry.js";
+import { safeTerminalLine } from "./safe-text.js";
+import { readSubagentSettings } from "./settings.js";
+
+export function assertNoSharedWriteConflict(
+	registry: AgentRegistry,
+	agentName: string,
+	cwd: string,
+	scope: AgentScope,
+	settings?: SubagentSettings,
+): void {
+	const agents = discoverAgents(cwd, scope, settings ?? readSubagentSettings()).agents;
+	const requested = agents.find((agent) => agent.name === agentName);
+	if (!isWriteCapable(requested?.tools)) return;
+	for (const active of registry.list()) {
+		if (
+			!isSameCwd(active.cwd, cwd) ||
+			(active.state !== "running" && active.state !== "starting")
+		) {
+			continue;
+		}
+		const activeConfig = agents.find((agent) => agent.name === active.agent);
+		if (isWriteCapable(activeConfig?.tools)) {
+			throw new Error(
+				`Write-capable subagent ${active.id} is already active in shared workspace ${cwd}. ` +
+					"Prefer one subagent_spawn covering combined asynchronous work. Use the blocking subagent parallel mode only when concurrent synchronous outputs justify making the main agent unavailable. Otherwise let the active agent finish or close it; set allowConcurrentWrites only when overlapping writes are knowingly safe, or use workspaceMode worktree when repository isolation is needed.",
+			);
+		}
+	}
+}
+
+export function assertFollowUpWriteAllowed(
+	registry: AgentRegistry,
+	agent: ManagedAgent,
+	allowConcurrentWrites: boolean,
+	isolatedWorkspace: boolean,
+	settings?: SubagentSettings,
+): void {
+	if (allowConcurrentWrites || isolatedWorkspace) return;
+	assertNoSharedWriteConflict(
+		registry,
+		agent.agent,
+		agent.cwd,
+		agent.agentScope ?? "user",
+		settings,
+	);
+}
+
+export function isWriteCapable(tools: string[] | undefined): boolean {
+	if (!tools) return true;
+	return tools.some((tool) => ["bash", "write", "edit"].includes(tool));
+}
+
+export async function confirmProjectAgent(
+	name: string,
+	scope: AgentScope,
+	confirm: boolean,
+	ctx: ExtensionContext,
+	cwd: string,
+	settings?: SubagentSettings,
+): Promise<void> {
+	if (scope !== "project" && scope !== "both") return;
+	if (!isSameCwd(cwd, ctx.cwd)) {
+		throw new Error("Project-local subagent definitions cannot run with an overridden cwd");
+	}
+	if (!ctx.isProjectTrusted()) {
+		throw new Error("Project-local subagent definitions require a trusted project");
+	}
+	const discovery = discoverAgents(cwd, scope, settings ?? readSubagentSettings());
+	const agent = discovery.agents.find((candidate) => candidate.name === name);
+	if (agent?.source !== "project") return;
+	if (confirm && ctx.hasUI) {
+		const approved = await ctx.ui.confirm(
+			"Run project-local agent?",
+			`Agent: ${safeTerminalLine(name, 256)}\nSource: ${safeTerminalLine(agent.filePath)}`,
+		);
+		if (!approved) throw new Error("Project-local subagent was not approved");
+	}
+}
+
+function isSameCwd(left: string, right: string): boolean {
+	try {
+		return realpathSync(left) === realpathSync(right);
+	} catch {
+		return path.resolve(left) === path.resolve(right);
+	}
+}